mirror of
https://github.com/boostorg/fiber.git
synced 2026-02-12 12:02:54 +00:00
a0490413cd
Explain "shared state", and provide links to the explanation wherever it's referenced. We don't need the doc to enumerate 'R& future<R&>::get()' or 'void future<void>::get()' separately from 'R future<R>::get()': all three specializations are exactly as the reader expects, given the generic template (unlike shared_future, where it's useful to spell them out). Encapsulate some of the necessary redundancies between future and shared_future documentation. Explain the effect of promise::set_value() vs. promise::set_exception() on each of [shared_]future::get(), get_exception_ptr(), wait(), wait_for() and wait_until(). Add get_exception_ptr() method to shared_future exposition class. Clarify distinction between shared_future move assignment vs. copy assignment. Document that async() is now variadic. Document its StackAllocator overload, and the effect of passing StackAllocator. Remove warning about launch policy 'deferred' since async() has no launch policy parameter.
353 lines
10 KiB
Plaintext
353 lines
10 KiB
Plaintext
[/
|
|
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.]]
|
|
]
|
|
|
|
[heading `deferred`]
|
|
[variablelist
|
|
[[Effects:] [The function is deferred, e.g. result will be computed only when explictly requested.]]
|
|
[[Note:] [Not implemented yet.]]
|
|
]
|
|
|
|
[warning Launch policy `deferred`, which indicates you simply want to defer the function call until a later time (lazy evaluation), is not supported yet.]
|
|
|
|
|
|
[template_heading future]
|
|
|
|
A __future__ contains a [link shared_state shared state] which is not shared with any other future.
|
|
|
|
template< typename R >
|
|
class future {
|
|
public:
|
|
future() noexcept;
|
|
|
|
future( future && other) noexcept;
|
|
|
|
future( future const& other) = delete;
|
|
|
|
~future();
|
|
|
|
future & operator=( future && other) noexcept;
|
|
|
|
future & operator=( future const& other) = delete;
|
|
|
|
bool valid() const noexcept;
|
|
|
|
shared_future< R > share();
|
|
|
|
R get();
|
|
|
|
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();
|
|
|
|
[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] == other.valid()]]]
|
|
[[Throws:] [Nothing.]]
|
|
]
|
|
]
|
|
[future_move_copy_ctor_variablelist future..false]
|
|
|
|
[heading Destructor]
|
|
|
|
~future();
|
|
|
|
[template future_dtor_variablelist[xfuture end]
|
|
[variablelist
|
|
[[Effects:] [Destroys the [xfuture]; ownership is abandoned[end]]]
|
|
[[Throws:] [Nothing.]]
|
|
]
|
|
]
|
|
[future_dtor_variablelist future .]
|
|
|
|
[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__.]]
|
|
[[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();
|
|
|
|
[template future_get_variablelist[]
|
|
[variablelist
|
|
[[Precondition:] [`true == valid()`]]
|
|
[[Returns:] [[future_method_wait .] If `set_value()` is called, returns the
|
|
value. If `set_exception()` is called, throws the indicated exception.]]
|
|
[[Postcondition:] [`false == valid()`]]
|
|
[[Throws:] [__future_error__ with error condition __no_state__, or
|
|
__fiber_interrupted__. 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__ or __fiber_interrupted__.]]
|
|
]
|
|
]
|
|
[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__ or __fiber_interrupted__.]]
|
|
]
|
|
|
|
[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 __fiber_interrupted__.]]
|
|
]
|
|
|
|
[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 __fiber_interrupted__.]]
|
|
]
|
|
]
|
|
[future_wait_etc future]
|
|
|
|
|
|
[template_heading shared_future]
|
|
|
|
A __shared_future__ contains a [link shared_state shared state] which might be shared with other futures.
|
|
|
|
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 && 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 && other) noexcept;
|
|
shared_future( shared_future && other) noexcept;
|
|
|
|
[future_move_copy_ctor_variablelist shared_future..false]
|
|
|
|
[heading Copy constructor]
|
|
|
|
shared_future( shared_future const& other) noexcept;
|
|
|
|
[future_move_copy_ctor_variablelist shared_future..true]
|
|
|
|
[heading Destructor]
|
|
|
|
~shared_future();
|
|
|
|
[future_dtor_variablelist shared_future.. if not shared.]
|
|
|
|
[operator_heading shared_future..operator_assign..operator=]
|
|
|
|
shared_future & operator=( future && 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: `true` 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>
|
|
|
|
template< typename Fn, typename ... Args >
|
|
future< typename result_of< Fn&&( Args && ... ) >::type >
|
|
async( Fn && fn, Args && ... args);
|
|
|
|
template< typename StackAllocator, typename Fn, typename ... Args >
|
|
future< typename result_of< Fn&&( Args && ... ) >::type >
|
|
async( std::allocator_arg_t, StackAllocator salloc, Fn && fn, Args && ... args);
|
|
|
|
[variablelist
|
|
[[Effects:] [Executes `fn` in a [class_link fiber] and returns an associated
|
|
[template_link future].]]
|
|
[[Result:] [`future< typename result_of< Fn >::type >` representing the [link
|
|
shared_state shared state] associated with the asynchronous execution of
|
|
`fn`.]]
|
|
[[Throws:] [__fiber_exception__ or __future_error__ if an error occurs.]]
|
|
[[Notes:] [The overload accepting `std::allocator_arg_t` uses the passed
|
|
`StackAllocator` when constructing the launched `fiber`.]]
|
|
]
|
|
|
|
[endsect]
|