123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428 |
- [/
- Copyright Oliver Kowalke 2013.
- Distributed under the Boost Software License, Version 1.0.
- (See accompanying file LICENSE_1_0.txt or copy at
- http://www.boost.org/LICENSE_1_0.txt
- ]
- [section:future Future]
- A future provides a mechanism to access the result of an asynchronous operation.
- [#shared_state]
- [heading shared state]
- Behind a [template_link promise] and its [template_link future] lies an
- unspecified object called their ['shared state]. The shared state is what will
- actually hold the async result (or the exception).
- The shared state is instantiated along with the [template_link promise].
- Aside from its originating `promise<>`, a [template_link future] holds a
- unique reference to a particular shared state. However, multiple
- [template_link shared_future] instances can reference the same underlying
- shared state.
- As [template_link packaged_task] and [ns_function_link fibers..async] are
- implemented using [template_link promise], discussions of shared state apply
- to them as well.
- [#class_future_status]
- [heading Enumeration `future_status`]
- Timed wait-operations (__wait_for__ and __wait_until__) return the state of the future.
- enum class future_status {
- ready,
- timeout,
- deferred // not supported yet
- };
- [heading `ready`]
- [variablelist
- [[Effects:] [The [link shared_state shared state] is ready.]]
- ]
- [heading `timeout`]
- [variablelist
- [[Effects:] [The [link shared_state shared state] did not become ready before timeout has passed.]]
- ]
- [note Deferred futures are not supported.]
- [template_heading future]
- A __future__ contains a [link shared_state shared state] which is not shared with any other future.
- #include <boost/fiber/future/future.hpp>
- namespace boost {
- namespace fibers {
- template< typename R >
- class future {
- public:
- future() noexcept;
- future( future const& other) = delete;
- future & operator=( future const& other) = delete;
- future( future && other) noexcept;
- future & operator=( future && other) noexcept;
- ~future();
- bool valid() const noexcept;
- shared_future< R > share();
- R get(); // member only of generic future template
- R & get(); // member only of future< R & > template specialization
- void get(); // member only of future< void > template specialization
- std::exception_ptr get_exception_ptr();
- void wait() const;
- template< class Rep, class Period >
- future_status wait_for(
- std::chrono::duration< Rep, Period > const& timeout_duration) const;
- template< typename Clock, typename Duration >
- future_status wait_until(
- std::chrono::time_point< Clock, Duration > const& timeout_time) const;
- };
- }}
- [heading Default constructor]
- future() noexcept;
- [template future_ctor_variablelist[xfuture]
- [variablelist
- [[Effects:] [Creates a [xfuture] with no [link shared_state shared state].
- After construction `false == valid()`.]]
- [[Throws:] [Nothing.]]
- ]
- ]
- [future_ctor_variablelist future]
- [heading Move constructor]
- future( future && other) noexcept;
- [template future_move_copy_ctor_variablelist[xfuture post_valid]
- [variablelist
- [[Effects:] [Constructs a [xfuture] with the [link shared_state shared state] of other.
- After construction [post_valid].]]
- [[Throws:] [Nothing.]]
- ]
- ]
- [future_move_copy_ctor_variablelist future..`false == other.valid()`]
- [heading Destructor]
- ~future();
- [template future_dtor_variablelist[xfuture end]
- [variablelist
- [[Effects:] [Destroys the [xfuture]; ownership is abandoned[end]]]
- [[Note:] [[`~[xfuture]()] does ['not] block the calling fiber.]]
- ]
- ]
- [future_dtor_variablelist future .]
- Consider a sequence such as:
- # instantiate [template_link promise]
- # obtain its `future<>` via [member_link promise..get_future]
- # launch [class_link fiber], capturing `promise<>`
- # destroy `future<>`
- # call [member_link promise..set_value]
- The final `set_value()` call succeeds, but the value is silently discarded: no
- additional `future<>` can be obtained from that `promise<>`.
- [operator_heading future..operator_assign..operator=]
- future & operator=( future && other) noexcept;
- [variablelist
- [[Effects:] [Moves the [link shared_state shared state] of other to `this`.
- After the assignment, `false == other.valid()`.]]
- [[Throws:] [Nothing.]]
- ]
- [template future_valid[xfuture]
- [member_heading [xfuture]..valid]
- bool valid() const noexcept;
- [variablelist
- [[Effects:] [Returns `true` if [xfuture] contains a [link shared_state shared state].]]
- [[Throws:] [Nothing.]]
- ]
- ]
- [future_valid future]
- [member_heading future..share]
- shared_future< R > share();
- [variablelist
- [[Effects:] [Move the state to a __shared_future__.]]
- [[Returns:] [a __shared_future__ containing the [link shared_state shared
- state] formerly belonging to `*this`.]]
- [[Postcondition:] [`false == valid()`]]
- [[Throws:] [__future_error__ with error condition __no_state__.]]
- ]
- [template future_method_wait[end] Waits until [member_link promise..set_value] or
- [member_link promise..set_exception] is called[end]]
- [member_heading future..get]
- R get(); // member only of generic future template
- R & get(); // member only of future< R & > template specialization
- void get(); // member only of future< void > template specialization
- [template future_get_variablelist[]
- [variablelist
- [[Precondition:] [`true == valid()`]]
- [[Returns:] [[future_method_wait .] If [member_link promise..set_value] is
- called, returns the value. If [member_link promise..set_exception] is called,
- throws the indicated exception.]]
- [[Postcondition:] [`false == valid()`]]
- [[Throws:] [__future_error__ with error condition __no_state__,
- __broken_promise__. Any exception passed to
- `promise::set_exception()`.]]
- ]
- ]
- [future_get_variablelist]
- [template future_get_exception_ptr[xfuture]
- [member_heading [xfuture]..get_exception_ptr]
- std::exception_ptr get_exception_ptr();
- [variablelist
- [[Precondition:] [`true == valid()`]]
- [[Returns:] [[future_method_wait .] If `set_value()` is called, returns a
- default-constructed `std::exception_ptr`. If `set_exception()` is called,
- returns the passed `std::exception_ptr`.]]
- [[Throws:] [__future_error__ with error condition __no_state__.]]
- [[Note:] [ `get_exception_ptr()` does ['not] invalidate the [`[xfuture]].
- After calling `get_exception_ptr()`, you may still call [member_link
- [xfuture]..get].]]
- ]
- ]
- [future_get_exception_ptr future]
- [template future_wait_etc[xfuture]
- [member_heading [xfuture]..wait]
- void wait();
- [variablelist
- [[Effects:] [[future_method_wait .]]]
- [[Throws:] [__future_error__ with error condition __no_state__.]]
- ]
- [template_member_heading [xfuture]..wait_for]
- template< class Rep, class Period >
- future_status wait_for( std::chrono::duration< Rep, Period > const& timeout_duration) const;
- [variablelist
- [[Effects:] [[future_method_wait , or `timeout_duration` has passed.]]]
- [[Result:] [A `future_status` is returned indicating the reason for returning.]]
- [[Throws:] [__future_error__ with error condition __no_state__ or
- timeout-related exceptions.]]
- ]
- [template_member_heading [xfuture]..wait_until]
- template< typename Clock, typename Duration >
- future_status wait_until( std::chrono::time_point< Clock, Duration > const& timeout_time) const;
- [variablelist
- [[Effects:] [[future_method_wait , or `timeout_time` has passed.]]]
- [[Result:] [A `future_status` is returned indicating the reason for returning.]]
- [[Throws:] [__future_error__ with error condition __no_state__ or
- timeout-related exceptions.]]
- ]
- ]
- [future_wait_etc future]
- [template_heading shared_future]
- A __shared_future__ contains a [link shared_state shared state] which might be
- shared with other __shared_future__ instances.
- #include <boost/fiber/future/future.hpp>
- namespace boost {
- namespace fibers {
- template< typename R >
- class shared_future {
- public:
- shared_future() noexcept;
- ~shared_future();
- shared_future( shared_future const& other);
- shared_future( future< R > && other) noexcept;
- shared_future( shared_future && other) noexcept;
- shared_future & operator=( shared_future && other) noexcept;
- shared_future & operator=( future< R > && other) noexcept;
- shared_future & operator=( shared_future const& other) noexcept;
- bool valid() const noexcept;
- R const& get(); // member only of generic shared_future template
- R & get(); // member only of shared_future< R & > template specialization
- void get(); // member only of shared_future< void > template specialization
- std::exception_ptr get_exception_ptr();
- void wait() const;
- template< class Rep, class Period >
- future_status wait_for(
- std::chrono::duration< Rep, Period > const& timeout_duration) const;
- template< typename Clock, typename Duration >
- future_status wait_until(
- std::chrono::time_point< Clock, Duration > const& timeout_time) const;
- };
- }}
- [heading Default constructor]
- shared_future();
- [future_ctor_variablelist shared_future]
- [heading Move constructor]
- shared_future( future< R > && other) noexcept;
- shared_future( shared_future && other) noexcept;
- [future_move_copy_ctor_variablelist shared_future..`false == other.valid()`]
- [heading Copy constructor]
- shared_future( shared_future const& other) noexcept;
- [future_move_copy_ctor_variablelist shared_future..`other.valid()` is unchanged]
- [heading Destructor]
- ~shared_future();
- [future_dtor_variablelist shared_future.. if not shared.]
- [operator_heading shared_future..operator_assign..operator=]
- shared_future & operator=( future< R > && other) noexcept;
- shared_future & operator=( shared_future && other) noexcept;
- shared_future & operator=( shared_future const& other) noexcept;
- [variablelist
- [[Effects:] [Moves or copies the [link shared_state shared state] of other to
- `this`. After the assignment, the state of `other.valid()` depends on which
- overload was invoked: unchanged for the overload accepting `shared_future
- const&`, otherwise `false`.]]
- [[Throws:] [Nothing.]]
- ]
- [future_valid shared_future]
- [member_heading shared_future..get]
- R const& get(); // member only of generic shared_future template
- R & get(); // member only of shared_future< R & > template specialization
- void get(); // member only of shared_future< void > template specialization
- [future_get_variablelist]
- [future_get_exception_ptr shared_future]
- [future_wait_etc shared_future]
- [ns_function_heading fibers..async]
- #include <boost/fiber/future/async.hpp>
- namespace boost {
- namespace fibers {
- template< class Function, class ... Args >
- future<
- std::result_of_t<
- std::decay_t< Function >( std::decay_t< Args > ... )
- >
- >
- async( Function && fn, Args && ... args);
- template< class Function, class ... Args >
- future<
- std::result_of_t<
- std::decay_t< Function >( std::decay_t< Args > ... )
- >
- >
- async( ``[link class_launch `launch`]`` policy, Function && fn, Args && ... args);
- template< typename __StackAllocator__, class Function, class ... Args >
- future<
- std::result_of_t<
- std::decay_t< Function >( std::decay_t< Args > ... )
- >
- >
- async( ``[link class_launch `launch`]`` policy, __allocator_arg_t__, __StackAllocator__ salloc,
- Function && fn, Args && ... args);
- template< typename __StackAllocator__, typename Allocator, class Function, class ... Args >
- future<
- std::result_of_t<
- std::decay_t< Function >( std::decay_t< Args > ... )
- >
- >
- async( ``[link class_launch `launch`]`` policy, __allocator_arg_t__, __StackAllocator__ salloc,
- Allocator alloc, Function && fn, Args && ... args);
- }}
- [variablelist
- [[Effects:] [Executes `fn` in a [class_link fiber] and returns an associated
- [template_link future].]]
- [[Result:] [``future<
- std::result_of_t<
- std::decay_t< Function >( std::decay_t< Args > ... )
- >
- >`` representing the [link
- shared_state shared state] associated with the asynchronous execution of
- `fn`.]]
- [[Throws:] [__fiber_error__ or __future_error__ if an error occurs.]]
- [[Notes:] [The overloads accepting __allocator_arg_t__ use the passed
- __StackAllocator__ when constructing the launched `fiber`. The overloads
- accepting [class_link launch] use the passed `launch` when
- constructing the launched `fiber`. The default `launch` is `post`, as
- for the `fiber` constructor.]]
- ]
- [note Deferred futures are not supported.]
- [endsect]
|