Google Git
Sign in
android / platform / external / sdv / vsomeip / 74879618 / . / third_party / boost / thread / doc / future_ref.qbk
blob: fa31f4c928ca3a4890b7ea5102d769d701a52b69 [file] [log] [blame]
[/
(C) Copyright 2008-11 Anthony Williams.
(C) Copyright 2012-2015 Vicente J. Botet Escriba.
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:reference Futures Reference]
//#include <boost/thread/future.hpp>
namespace boost
{
namespace future_state // EXTENSION
{
enum state {uninitialized, waiting, ready, moved};
}
enum class future_errc
{
broken_promise,
future_already_retrieved,
promise_already_satisfied,
no_state
};
enum class launch
{
none = unspecified,
async = unspecified,
deferred = unspecified,
executor = unspecified,
inherit = unspecified,
any = async | deferred
};
enum class future_status {
ready, timeout, deferred
};
namespace system
{
template <>
struct is_error_code_enum<future_errc> : public true_type {};
error_code make_error_code(future_errc e);
error_condition make_error_condition(future_errc e);
}
const system::error_category& future_category();
class future_error;
class exceptional_ptr;
template <typename R>
class promise;
template <typename R>
void swap(promise<R>& x, promise<R>& y) noexcept;
namespace container {
template <class R, class Alloc>
struct uses_allocator<promise<R>, Alloc>:: true_type;
}
template <typename R>
class future;
template <typename R>
class shared_future;
template <typename S>
class packaged_task;
template <class S> void swap(packaged_task<S>&, packaged_task<S>&) noexcept;
template <class S, class Alloc>
struct uses_allocator<packaged_task <S>, Alloc>;
template <class F>
future<typename result_of<typename decay<F>::type()>::type>
async(F f);
template <class F>
future<typename result_of<typename decay<F>::type()>::type>
async(launch policy, F f);
template <class F, class... Args>
future<typename result_of<typename decay<F>::type(typename decay<Args>::type...)>::type>
async(F&& f, Args&&... args);
template <class F, class... Args>
future<typename result_of<typename decay<F>::type(typename decay<Args>::type...)>::type>
async(launch policy, F&& f, Args&&... args);
template <class Executor, class F, class... Args>
future<typename result_of<typename decay<F>::type(typename decay<Args>::type...)>::type>
async(Executor &ex, F&& f, Args&&... args);
template<typename Iterator>
void wait_for_all(Iterator begin,Iterator end); // EXTENSION
template<typename F1,typename... FS>
void wait_for_all(F1& f1,Fs&... fs); // EXTENSION
template<typename Iterator>
Iterator wait_for_any(Iterator begin,Iterator end); // EXTENSION
template<typename F1,typename... Fs>
unsigned wait_for_any(F1& f1,Fs&... fs); // EXTENSION
template <class InputIterator>
future<std::vector<typename InputIterator::value_type::value_type>>
when_all(InputIterator first, InputIterator last);
template <typename... T>
future<std::tuple<decay_t<T>...> when_all(T&&... futures);
template <class InputIterator>
future<std::vector<typename InputIterator::value_type::value_type>>
when_any(InputIterator first, InputIterator last); // EXTENSION
template <typename... T>
future<std::tuple<decay_t<T>...> when_any(T&&... futures);
template <typename T>
future<typename decay<T>::type> make_future(T&& value); // DEPRECATED
future<void> make_future(); // DEPRECATED
template <typename T>
future<typename decay<T>::type> make_ready_future(T&& value); // EXTENSION
future<void> make_ready_future(); // EXTENSION
exceptional_ptr make_exceptional_future(exception_ptr ex); // EXTENSION
template <typename E>
exceptional_ptr make_exceptional_future(E ex); // EXTENSION
exceptional_ptr make_exceptional_future(); // EXTENSION
template <typename T>
shared_future<typename decay<T>::type> make_shared_future(T&& value); // DEPRECATED
shared_future<void> make_shared_future(); // DEPRECATED
[////////////////////////////////////////]
[section:future_state Enumeration `state`]
namespace future_state
{
enum state {uninitialized, waiting, ready, moved};
}
[endsect]
[/////////////////////////////////////////////]
[section:future_errc Enumeration `future_errc`]
enum class future_errc
{
broken_promise = implementation defined,
future_already_retrieved = implementation defined,
promise_already_satisfied = implementation defined,
no_state = implementation defined
}
The enum values of future_errc are distinct and not zero.
[endsect]
[///////////////////////////////////]
[section:launch Enumeration `launch`]
enum class launch
{
none = unspecified,
async = unspecified,
deferred = unspecified,
executor = unspecified,
inherit = unspecified,
any = async | deferred
};
The enum type launch is a bitmask type with launch::async and launch::deferred denoting individual bits.
A future created with `promise<>` or with a `packaged_task<>` or with `make_ready_future`/`make_exceptional_future` (has no associated launch policy), has an implicit a launch policy of `launch::none`.
A future created by `async(launch::async, ...)` or `::then(launch::async, ...)` has associated a launch policy `launch::async`.
A future created by `async(launch::deferred, ...)` or `::then(launch::deferred, ...)` has associated a launch policy `launch::deferred`.
A future created by `async(Executor, ...)` or `::then(Executor, ...)` or `::then(launch::executor, ...)` has associated a launch policy `launch::executor`.
A future created by `async(...)` or `::then(...)` has associated a launch policy `launch::none`.
A future created by `::then(launch::inherit, ...)` has associated a launch policy parent future.
The `executor` and the `inherit` launch policies have a sense only can be user only on `then()`.
[endsect]
[///////////////////////////////////////////////////////////////////////////]
[section:is_error_code_enum Specialization `is_error_code_enum<future_errc>`]
namespace system
{
template <>
struct is_error_code_enum<future_errc> : public true_type {};
}
[endsect]
[///////////////////////////////////////////////////////////////]
[section:make_error_code Non-member function `make_error_code()`]
namespace system
{
error_code make_error_code(future_errc e);
}
[variablelist
[[Returns:] [`error_code(static_cast<int>(e), future_category())`.]]
]
[endsect]
[/////////////////////////////////////////////////////////////////////////]
[section:make_error_condition Non-member function `make_error_condition()`]
namespace system
{
error_condition make_error_condition(future_errc e);
}
[variablelist
[[Returns:] [`error_condition(static_cast<int>(e), future_category())`.]]
]
[endsect]
[///////////////////////////////////////////////////////////////]
[section:future_category Non-member function `future_category()`]
const system::error_category& future_category();
[variablelist
[[Returns:] [A reference to an object of a type derived from class error_category.]]
[[Notes:] [The object's `default_error_condition` and equivalent virtual functions behave as specified for the class `system::error_category`.
The object's `name` virtual function returns a pointer to the string "future".]]
]
[endsect]
[/////////////////////////////////////////]
[section:future_error Class `future_error`]
class future_error
: public std::logic_error
{
public:
future_error(system::error_code ec);
const system::error_code& code() const no_except;
};
[///////////////////////////////]
[section:constructor Constructor]
future_error(system::error_code ec);
[variablelist
[[Effects:] [Constructs a future_error.]]
[[Postconditions:] [`code()==ec` ]]
[[Throws:] [Nothing.]]
]
[endsect]
[/////////////////////////////////////]
[section:code Member function `code()`]
const system::error_code& code() const no_except;
[variablelist
[[Returns:] [The value of `ec` that was passed to the object's constructor.]]
]
[endsect]
[endsect]
[/////////////////////////////////////////////////]
[section:future_status Enumeration `future_status`]
enum class future_status {
ready, timeout, deferred
};
[endsect]
[/////////////////////////////////////////]
[section:future_error Class `exceptional_ptr` EXPERIMENTAL]
class exceptional_ptr
{
public:
exceptional_ptr();
explicit exceptional_ptr(exception_ptr ex);
template <class E>
explicit exceptional_ptr(E&& ex);
};
[///////////////////////////////]
[section:constructor Constructor]
exceptional_ptr();
explicit exceptional_ptr(exception_ptr ex);
template <class E>
explicit exceptional_ptr(E&& ex);
[variablelist
[[Effects:] [The exception that is passed in to the constructor or the current exception if no parameter is moved into the constructed `exceptional_ptr` if it is an rvalue. Otherwise the exception is copied into the constructed `exceptional_ptr`.]]
[[Postconditions:] [
`valid() == true && is_ready() = true && has_value() = false`
]]
[[Throws:] [Nothing.]]
]
[endsect]
[endsect]
[////////////////////////////////////////////////////]
[section:unique_future __unique_future class template]
template <typename R>
class __unique_future__
{
public:
typedef R value_type; // EXTENSION
__unique_future__(__unique_future__ const& rhs) = delete;
__unique_future__& operator=(__unique_future__ const& rhs) = delete;
__unique_future__() noexcept;
~__unique_future__();
// move support
__unique_future__(__unique_future__ && other) noexcept;
explicit __unique_future__(__unique_future__<__unique_future__<R>>&& rhs); // EXTENSION
__unique_future__& operator=(__unique_future__ && other) noexcept;
// factories
shared_future<R> share();
template<typename F>
__unique_future__<typename boost::result_of<F(__unique_future__)>::type>
then(F&& func); // EXTENSION
template<typename Ex, typename F>
__unique_future__<typename boost::result_of<F(__unique_future__)>::type>
then(Ex& executor, F&& func); // EXTENSION
template<typename F>
__unique_future__<typename boost::result_of<F(__unique_future__)>::type>
then(launch policy, F&& func); // EXTENSION
see below unwrap(); // EXTENSION
__unique_future__ fallback_to(); // EXTENSION
void swap(__unique_future__& other) noexcept;
// retrieving the value
see below get();
see below get_or(see below); // EXTENSION
exception_ptr get_exception_ptr(); // EXTENSION
// functions to check state
bool valid() const noexcept;
bool is_ready() const; // EXTENSION
bool has_exception() const; // EXTENSION
bool has_value() const; // EXTENSION
// waiting for the result to be ready
void wait() const;
template <class Rep, class Period>
future_status wait_for(const chrono::duration<Rep, Period>& rel_time) const;
template <class Clock, class Duration>
future_status wait_until(const chrono::time_point<Clock, Duration>& abs_time) const;
#if defined BOOST_THREAD_USES_DATE_TIME
template<typename Duration>
bool timed_wait(Duration const& rel_time) const; // DEPRECATED SINCE V3.0.0
bool timed_wait_until(boost::system_time const& abs_time) const; // DEPRECATED SINCE V3.0.0
#endif
typedef future_state::state state; // EXTENSION
state get_state() const; // EXTENSION
};
[///////////////////////////////////////////////]
[section:default_constructor Default Constructor]
__unique_future__();
[variablelist
[[Effects:] [Constructs an uninitialized __unique_future__.]]
[[Postconditions:] [[unique_future_is_ready_link `this->is_ready`] returns `false`. [unique_future_get_state_link
`this->get_state()`] returns __uninitialized__.]]
[[Throws:] [Nothing.]]
]
[endsect]
[/////////////////////////////]
[section:destructor Destructor]
~__unique_future__();
[variablelist
[[Effects:] [Destroys `*this`.]]
[[Throws:] [Nothing.]]
]
[endsect]
[/////////////////////////////////////////]
[section:move_constructor Move Constructor]
__unique_future__(__unique_future__ && other);
[variablelist
[[Effects:] [Constructs a new __unique_future__, and transfers ownership of the shared state associated with `other` to `*this`.]]
[[Postconditions:] [[unique_future_get_state_link `this->get_state()`] returns the value of `other->get_state()` prior to the
call. `other->get_state()` returns __uninitialized__. If `other` was associated with a shared state, that result is now
associated with `*this`. `other` is not associated with any shared state.]]
[[Throws:] [Nothing.]]
[[Notes:] [If the compiler does not support rvalue-references, this is implemented using the boost.thread move emulation.]]
]
[endsect]
[///////////////////////////////////////////////////////////////////]
[section:unwrap_move_constructor Unwrap Move Constructor - EXTENSION]
explicit __unique_future__(__unique_future__<__unique_future__<R>>&& other); // EXTENSION
[warning This constructor is experimental and subject to change in future versions.
There are not too much tests yet, so it is possible that you can find out some trivial bugs :(]
[variablelist
[[Requires:] [`other.valid()`.]
[[Effects:] [Constructs a new __unique_future__, and transfers ownership of the shared state associated with `other` and unwrapping the inner future (see `unwrap()`).]]
[[Postconditions:] [[unique_future_get_state_link `this->get_state()`] returns the value of `other->get_state()` prior to the
call. `other->get_state()` returns __uninitialized__. The associated shared state is now
unwrapped and the inner future shared state is associated with `*this`. `other` is not associated with any shared state, `! other.valid()`.]]
[[Throws:] [Nothing.]]
[[Notes:] [If the compiler does not support rvalue-references, this is implemented using the boost.thread move emulation.]]
]
[endsect]
[////////////////////////////////////////////////]
[section:move_assignment Move Assignment Operator]
__unique_future__& operator=(__unique_future__ && other);
[variablelist
[[Effects:] [Transfers ownership of the shared state associated with `other` to `*this`.]]
[[Postconditions:] [[unique_future_get_state_link `this->get_state()`] returns the value of `other->get_state()` prior to the
call. `other->get_state()` returns __uninitialized__. If `other` was associated with a shared state, that result is now
associated with `*this`. `other` is not associated with any shared state. If `*this` was associated with an asynchronous
result prior to the call, that result no longer has an associated __unique_future__ instance.]]
[[Throws:] [Nothing.]]
[[Notes:] [If the compiler does not support rvalue-references, this is implemented using the boost.thread move emulation.]]
]
[endsect]
[/////////////////////////////////////]
[section:swap Member function `swap()`]
void swap(__unique_future__ & other) no_except;
[variablelist
[[Effects:] [Swaps ownership of the shared states associated with `other` and `*this`.]]
[[Postconditions:] [[unique_future_get_state_link `this->get_state()`] returns the value of `other->get_state()` prior to the
call. `other->get_state()` returns the value of `this->get_state()` prior to the call. If `other` was associated with a
shared state, that result is now associated with `*this`, otherwise `*this` has no associated result. If `*this` was
associated with a shared state, that result is now associated with `other`, otherwise `other` has no associated result.]]
[[Throws:] [Nothing.]]
]
[endsect]
[///////////////////////////////////]
[section:get Member function `get()`]
R get();
R& __unique_future__<R&>::get();
void __unique_future__<void>::get();
[variablelist
[[Effects:] [If `*this` is associated with a shared state, waits until the result is ready as-if by a call to
__unique_future_wait__, and retrieves the result (whether that is a value or an exception).]]
[[Returns:] [
- `__unique_future__<R&>::get()` return the stored reference.
- `__unique_future__<void>::get()`, there is no return value.
- `__unique_future__<R>::get()` returns an rvalue-reference to the value stored in the shared state.
]]
[[Postconditions:] [[unique_future_is_ready_link `this->is_ready()`] returns `true`. [unique_future_get_state_link
`this->get_state()`] returns __ready__.]]
[[Throws:] [
- __future_uninitialized__ if `*this` is not associated with a shared state.
- __thread_interrupted__ if the result associated with `*this` is not ready at the point of the call, and the current thread is interrupted.
- Any exception stored in the shared state in place of a value.
]]
[[Notes:] [`get()` is an ['interruption point].]]
]
[endsect]
[/////////////////////////////////////////////////////]
[section:get_or Member function `get_or()` - EXTENSION]
R get_or(R&& v); // EXTENSION
R get_or(R const& v); // EXTENSION
R& __unique_future__<R&>::get_or(R& v); // EXTENSION
void __unique_future__<void>::get_or(); // EXTENSION
[warning These functions are experimental and subject to change in future versions.
There are not too much tests yet, so it is possible that you can find out some trivial bugs :(]
[variablelist
[[Effects:] [If `*this` is associated with a shared state, waits until the result is ready as-if by a call to
__unique_future_wait__, and depending on whether the shared state `has_value()` the retrieves the result.]]
[[Returns:] [
- `__unique_future__<R&>::get_or(v)` return the stored reference if has_value() and the passes parameter otherwise.
- `__unique_future__<void>::get_or()`, there is no return value, but the function doesn't throws even if the shared state contained an exception.
- `__unique_future__<R>::get_or(v)` returns an rvalue-reference to the value stored in the shared state if `has_value()` and an rvalue-reference build with the parameter `v`.
]]
[[Postconditions:] [[unique_future_is_ready_link `this->is_ready()`] returns `true`. [unique_future_get_state_link
`this->get_state()`] returns __ready__.]]
[[Throws:] [
- __future_uninitialized__ if `*this` is not associated with a shared state.
]]
[[Notes:] [`get_or()` is an ['interruption point].]]
]
[endsect]
[/////////////////////////////////////]
[section:wait Member function `wait()`]
void wait() const;
[variablelist
[[Effects:] [If `*this` is associated with a shared state, waits until the result is ready. If the result is not ready on
entry, and the result has a ['wait callback] set, that callback is invoked prior to waiting.]]
[[Throws:] [
- __future_uninitialized__ if `*this` is not associated with a shared state.
- __thread_interrupted__ if the result
associated with `*this` is not ready at the point of the call, and the current thread is interrupted.
- Any exception thrown by the ['wait callback] if such a callback is called.]]
[[Postconditions:] [[unique_future_is_ready_link `this->is_ready()`] returns `true`. [unique_future_get_state_link
`this->get_state()`] returns __ready__.]]
[[Notes:] [`wait()` is an ['interruption point].]]
]
[endsect]
[//////////////////////////////////////////////////////////////////////////////////]
[section:timed_wait_duration Member function `timed_wait()` DEPRECATED SINCE V3.0.0]
template<typename Duration>
bool timed_wait(Duration const& wait_duration);
[warning
DEPRECATED since 3.00.
Use instead __wait_for.
]
[variablelist
[[Effects:] [If `*this` is associated with a shared state, waits until the result is ready, or the time specified by
`wait_duration` has elapsed. If the result is not ready on entry, and the result has a ['wait callback] set, that callback is
invoked prior to waiting.]]
[[Returns:] [`true` if `*this` is associated with a shared state, and that result is ready before the specified time has
elapsed, `false` otherwise.]]
[[Throws:] [
- __future_uninitialized__ if `*this` is not associated with a shared state.
- __thread_interrupted__ if the result associated with `*this` is not ready at the point of the call, and the current thread is interrupted.
- Any exception thrown by the ['wait callback] if such a callback is called.]]
[[Postconditions:] [If this call returned `true`, then [unique_future_is_ready_link `this->is_ready()`] returns `true` and
[unique_future_get_state_link `this->get_state()`] returns __ready__.]]
[[Notes:] [`timed_wait()` is an ['interruption point]. `Duration` must be a type that meets the Boost.DateTime time duration requirements.]]
]
[endsect]
[//////////////////////////////////////////////////////////////////////////////////]
[section:timed_wait_absolute Member function `timed_wait()` DEPRECATED SINCE V3.0.0]
bool timed_wait(boost::system_time const& wait_timeout);
[warning
DEPRECATED since 3.00.
Use instead __wait_until.
]
[variablelist
[[Effects:] [If `*this` is associated with a shared state, waits until the result is ready, or the time point specified by
`wait_timeout` has passed. If the result is not ready on entry, and the result has a ['wait callback] set, that callback is invoked
prior to waiting.]]
[[Returns:] [`true` if `*this` is associated with a shared state, and that result is ready before the specified time has
passed, `false` otherwise.]]
[[Throws:] [
- __future_uninitialized__ if `*this` is not associated with a shared state.
- __thread_interrupted__ if the result associated with `*this` is not ready at the point of the call, and the current thread is interrupted.
- Any exception thrown by the ['wait callback] if such a callback is called.]]
[[Postconditions:] [If this call returned `true`, then [unique_future_is_ready_link `this->is_ready()`] returns `true` and
[unique_future_get_state_link `this->get_state()`] returns __ready__.]]
[[Notes:] [`timed_wait()` is an ['interruption point].]]
]
[endsect]
[/////////////////////////////////////////////]
[section:wait_for Member function `wait_for()`]
template <class Rep, class Period>
future_status wait_for(const chrono::duration<Rep, Period>& rel_time) const;
[variablelist
[[Effects:] [If `*this` is associated with a shared state, waits until the result is ready, or the time specified by
`wait_duration` has elapsed. If the result is not ready on entry, and the result has a ['wait callback] set, that callback is
invoked prior to waiting.]]
[[Returns:] [
- `future_status::deferred` if the shared state contains a deferred function. (Not implemented yet)
- `future_status::ready` if the shared state is ready.
- `future_status::timeout` if the function is returning because the relative timeout specified by `rel_time` has expired.
]]
[[Throws:] [
- __future_uninitialized__ if `*this` is not associated with a shared state.
- __thread_interrupted__ if the result associated with `*this` is not ready at the point of the call, and the current thread is interrupted.
- Any exception thrown by the ['wait callback] if such a callback is called.]]
[[Postconditions:] [If this call returned `true`, then [unique_future_is_ready_link `this->is_ready()`] returns `true` and
[unique_future_get_state_link `this->get_state()`] returns __ready__.]]
[[Notes:] [`wait_for()` is an ['interruption point]. `Duration` must be a type that meets the Boost.DateTime time duration requirements.]]
]
[endsect]
[/////////////////////////////////////////////////]
[section:wait_until Member function `wait_until()`]
template <class Clock, class Duration>
future_status wait_until(const chrono::time_point<Clock, Duration>& abs_time) const;
[variablelist
[[Effects:] [If `*this` is associated with a shared state, waits until the result is ready, or the time point specified by
`wait_timeout` has passed. If the result is not ready on entry, and the result has a ['wait callback] set, that callback is invoked
prior to waiting.]]
[[Returns:] [
- `future_status::deferred` if the shared state contains a deferred function. (Not implemented yet)
- `future_status::ready` if the shared state is ready.
- `future_status::timeout` if the function is returning because the absolute timeout specified by `absl_time` has reached.
]]
[[Throws:] [
- __future_uninitialized__ if `*this` is not associated with a shared state.
- __thread_interrupted__ if the result associated with `*this` is not ready at the point of the call, and the current thread is interrupted.
- Any exception thrown by the ['wait callback] if such a callback is called.]]
[[Postconditions:] [If this call returned `true`, then [unique_future_is_ready_link `this->is_ready()`] returns `true` and
[unique_future_get_state_link `this->get_state()`] returns __ready__.]]
[[Notes:] [`wait_until()` is an ['interruption point].]]
]
[endsect]
[///////////////////////////////////////]
[section:valid Member function `valid()`]
bool valid() const noexcept;
[variablelist
[[Returns:] [`true` if `*this` is associated with a shared state, `false`
otherwise.]]
[[Remarks:] [The result of this function is not stable and that the future could become invalid even if the function returned true or vice-versa.]]
[[Throws:] [Nothing.]]
]
[endsect]
[///////////////////////////////////////////////////////]
[section:is_ready Member function `is_ready()` EXTENSION]
bool is_ready() const;
[variablelist
[[Returns:] [`true` if `*this` is associated with a shared state and that result is ready for retrieval, `false`
otherwise.]]
[[Remarks:] [The result of this function is not stable and that the future could become not ready even if the function returned true or vice-versa.]]
[[Throws:] [Nothing.]]
]
[endsect]
[/////////////////////////////////////////////////////////]
[section:has_value Member function `has_value()` EXTENSION]
bool has_value() const;
[variablelist
[[Returns:] [`true` if `*this` is associated with a shared state, that result is ready for retrieval, and the result is a
stored value, `false` otherwise.]]
[[Remarks:] [The result of this function is not stable and the future could lost its value even if the function returned true or vice-versa.]]
[[Throws:] [Nothing.]]
]
[endsect]
[/////////////////////////////////////////////////////////////////]
[section:has_exception Member function `has_exception()` EXTENSION]
bool has_exception() const;
[variablelist
[[Returns:] [`true` if `*this` is associated with a shared state, that result is ready for retrieval, and the result is a
stored exception, `false` otherwise.]]
[[Remarks:] [The result of this function is not stable and the future could lost its exception even if the function returned true or vice-versa.]]
[[Throws:] [Nothing.]]
]
[endsect]
[/////////////////////////////////////////////////////////////////]
[section:get_exception_ptr Member function `get_exception_ptr()` EXTENSION]
exception_ptr get_exception_ptr();
[variablelist
[[Effects:] [If `*this` is associated with a shared state, waits until the result is ready. If the result is not ready on
entry, and the result has a ['wait callback] set, that callback is invoked prior to waiting.]]
[[Returns:] [an exception_ptr, storing or not an exception.]]
[[Remarks:] [The result of this function is not stable and the future could lost its exception even if the function returned a valid `exception_ptr` or vice-versa.]]
[[Throws:] [Whatever `mutex::lock()/mutex::unlock()` can throw.]]
]
[endsect]
[/////////////////////////////////////////////////////////]
[section:get_state Member function `get_state()` EXTENSION]
future_state::state get_state();
[variablelist
[[Effects:] [Determine the state of the shared state associated with `*this`, if any.]]
[[Returns:] [__uninitialized__ if `*this` is not associated with a shared state. __ready__ if the shared state
associated with `*this` is ready for retrieval, __waiting__ otherwise.]]
[[Remarks:] [The result of this function is not stable.]]
[[Throws:] [Nothing.]]
]
[endsect]
[///////////////////////////////////////]
[section:share Member function `share()`]
shared_future<R> share();
[variablelist
[[Returns:] [`shared_future<R>(boost::move(*this))`.]]
[[Postconditions:] [`this->valid() == false`.]]
]
[endsect]
[/////////////////////////////////////////////////]
[section:then Member function `then()` - EXTENSION]
template<typename F>
__unique_future__<typename boost::result_of<F(__unique_future__)>::type>
then(F&& func); // EXTENSION
template<typename Ex, typename F>
__unique_future__<typename boost::result_of<F(__unique_future__)>::type>
then(Ex& executor, F&& func); // EXTENSION
template<typename F>
__unique_future__<typename boost::result_of<F(__unique_future__)>::type>
then(launch policy, F&& func); // EXTENSION
[warning These functions are experimental and subject to change in future versions.
There are not too much tests yet, so it is possible that you can find out some trivial bugs :(]
[note These functions are based on the [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3634.pdf [*N3634 - Improvements to std::future<T> and related APIs]] C++1y proposal by N. Gustafsson, A. Laksberg, H. Sutter, S. Mithani.]
[variablelist
[[Notes:] [The three functions differ only by input parameters. The first only takes a callable object which accepts a
future object as a parameter. The second function takes an executor as the first parameter and a callable object as
the second parameter. The third function takes a launch policy as the first parameter and a callable object as the
second parameter.]]
[[Requires:] [`INVOKE(DECAY_COPY (std::forward<F>(func)), std::move(*this))` shall be a valid expression.]]
[[Effects:] [
All the functions create a shared state that is associated with the returned future object. Additionally,
- When the object's shared state is ready, the continuation
`INVOKE(DECAY_COPY(std::forward<F>(func)), std::move(*this))` is called depending on the overload (see below) with the call to DECAY_COPY() being evaluated in the thread that called then.
- Any value returned from the continuation is stored as the result in the shared state of the resulting `future`.
Any exception propagated from the execution of the continuation is stored as the exceptional result in the shared state of the resulting `future`.
The continuation launches according to the specified policy or executor or noting.
- When the launch policy is `launch::none` the continuation is called on an unspecified thread of execution.
- When the launch policy is `launch::async` the continuation is called on a new thread of execution.
- When the launch policy is `launch::deferred` the continuation is called on demand.
- When the launch policy is `launch::executor` the continuation is called on one of the thread of execution of the executor.
- When the launch policy is `launch::inherit` the continuation inherits the parent's launch policy or executor.
- When the executor or launch policy is not provided (first overload) is if as if launch::none was specified.
- When the executor is provided (second overload) the continuation is called on one of the thread of execution of the executor.
- If the parent has a policy of `launch::deferred` and the continuation does not have a specified launch policy
executor, then the parent is filled by immediately calling `.wait()`, and the policy of the antecedent is
`launch::deferred`.
]]
[[Returns:] [An object of type `__unique_future__<typename boost::result_of<F(__unique_future__)>` that refers to the shared state created by the continuation.]]
[[Notes:] [
- Note that nested futures are not implicitly unwrapped yet. This could be subject to change in future versions.
- The returned futures behave as the ones returned from boost::async, the destructor of the future object returned from then will block. This could be subject to change in future versions.
]]
[[Postconditions:] [
- The `__unique_future__` object passed to the parameter of the continuation function is a copy of the original `__unique_future__`.
- `valid() == false` on original future; `valid() == true` on the `future` returned from then.
[/ In case of implicit unwrapping, the validity of the `future` returned from `then` cannot be established until after the completion of the functor passed into `then`. In such case, the resulting `future` becomes ready with an exception of type `future_error`, with an error code of `future_errc::broken_promise`. ]
]]
]
[endsect]
[///////////////////////////////////////////////////]
[section:unwrap Member function `unwrap()` EXTENSION]
template <typename R2>
__unique_future__<R2> __unique_future__<__unique_future__<R2>>::unwrap(); // EXTENSION
template <typename R2>
__shared_future__<R2> __unique_future__<__shared_future__<R2>>::unwrap(); // EXTENSION
[warning These functions are experimental and subject to change in future versions.
There are not too much tests yet, so it is possible that you can find out some trivial bugs :(]
[note These functions are based on the [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3634.pdf [*N3634 - Improvements to std::future<T> and related APIs]] C++1y proposal by N. Gustafsson, A. Laksberg, H. Sutter, S. Mithani.]
[variablelist
[[Notes:] [Removes the outermost future and returns a future with the associated state been a proxy of the outer future.]]
[[Effects:] [
- Returns a future that becomes ready when the shared state of the outer and inner future is ready. The validity of the future returned from `get()` applied on the outer future cannot be established a priori. If it is not valid, this future is forced to be valid and becomes ready with an exception of type `future_error`, with an error code of `future_errc::broken_promise`.
]]
[[Returns:] [An object of type future with the associated state been a proxy of outer future.]]
[[Postconditions:] [
- The returned future has `valid() == true`.
]]
]
[endsect]
[endsect]
[////////////////////////////////////////////////////]
[section:shared_future `shared_future` class template]
template <typename R>
class shared_future
{
public:
typedef future_state::state state; // EXTENSION
typedef R value_type; // EXTENSION
shared_future() noexcept;
~shared_future();
// copy support
shared_future(shared_future const& other);
shared_future& operator=(shared_future const& other);
// move support
shared_future(shared_future && other) noexcept;
shared_future(__unique_future__<R> && other) noexcept;
shared_future& operator=(shared_future && other) noexcept;
shared_future& operator=(__unique_future__<R> && other) noexcept;
// factories
template<typename F>
__unique_future__<typename boost::result_of<F(shared_future)>::type>
then(F&& func) const; // EXTENSION
template<typename S, typename F>
__unique_future__<typename boost::result_of<F(shared_future)>::type>
then(S& scheduler, F&& func) const; // EXTENSION
template<typename F>
__unique_future__<typename boost::result_of<F(shared_future)>::type>
then(launch policy, F&& func) const; // EXTENSION
void swap(shared_future& other);
// retrieving the value
see below get() const;
exception_ptr get_exception_ptr(); // EXTENSION
// functions to check state, and wait for ready
bool valid() const noexcept;
bool is_ready() const noexcept; // EXTENSION
bool has_exception() const noexcept; // EXTENSION
bool has_value() const noexcept; // EXTENSION
// waiting for the result to be ready
void wait() const;
template <class Rep, class Period>
future_status wait_for(const chrono::duration<Rep, Period>& rel_time) const;
template <class Clock, class Duration>
future_status wait_until(const chrono::time_point<Clock, Duration>& abs_time) const;
#if defined BOOST_THREAD_USES_DATE_TIME || defined BOOST_THREAD_DONT_USE_CHRONO
template<typename Duration>
bool timed_wait(Duration const& rel_time) const; // DEPRECATED SINCE V3.0.0
bool timed_wait_until(boost::system_time const& abs_time) const; // DEPRECATED SINCE V3.0.0
#endif
state get_state() const noexcept; // EXTENSION
};
[///////////////////////////////////////////////]
[section:default_constructor Default Constructor]
shared_future();
[variablelist
[[Effects:] [Constructs an uninitialized shared_future.]]
[[Postconditions:] [[shared_future_is_ready_link `this->is_ready`] returns `false`. [shared_future_get_state_link
`this->get_state()`] returns __uninitialized__.]]
[[Throws:] [Nothing.]]
]
[endsect]
[///////////////////////////////////]
[section:get Member function `get()`]
const R& get() const;
R& get() const;
void get() const;
[variablelist
[[Effects:] [If `*this` is associated with a shared state, waits until the result is ready as-if by a call to
__shared_future_wait__, and returns a `const` reference to the result.]]
[[Returns:] [
- `shared_future<R&>::get()` return the stored reference.
- `shared_future<void>::get()`, there is no return value.
- `shared_future<R>::get()` returns a `const` reference to the value stored in the shared state.
]]
[[Throws:] [
- __future_uninitialized__ if `*this` is not associated with a shared state.
- __thread_interrupted__ if the result associated with `*this` is not ready at the point of the call, and the current thread is interrupted.
]]
[[Notes:] [`get()` is an ['interruption point].]]
]
[endsect]
[/////////////////////////////////////]
[section:wait Member function `wait()`]
void wait() const;
[variablelist
[[Effects:] [If `*this` is associated with a shared state, waits until the result is ready. If the result is not ready on
entry, and the result has a ['wait callback] set, that callback is invoked prior to waiting.]]
[[Throws:] [
- __future_uninitialized__ if `*this` is not associated with a shared state.
- __thread_interrupted__ if the result associated with `*this` is not ready at the point of the call, and the current thread is interrupted.
- Any exception thrown by the
['wait callback] if such a callback is called.]]
[[Postconditions:] [[shared_future_is_ready_link `this->is_ready()`] returns `true`. [shared_future_get_state_link
`this->get_state()`] returns __ready__.]]
[[Notes:] [`wait()` is an ['interruption point].]]
]
[endsect]
[//////////////////////////////////////////////////////////]
[section:timed_wait_duration Member function `timed_wait()`]
template<typename Duration>
bool timed_wait(Duration const& wait_duration);
[variablelist
[[Effects:] [If `*this` is associated with a shared state, waits until the result is ready, or the time specified by
`wait_duration` has elapsed. If the result is not ready on entry, and the result has a ['wait callback] set, that callback is
invoked prior to waiting.]]
[[Returns:] [`true` if `*this` is associated with a shared state, and that result is ready before the specified time has
elapsed, `false` otherwise.]]
[[Throws:] [
- __future_uninitialized__ if `*this` is not associated with a shared state.
- __thread_interrupted__ if the result associated with `*this` is not ready at the point of the call, and the current thread is interrupted.
- Any exception thrown by the ['wait callback] if such a callback is called.]]
[[Postconditions:] [If this call returned `true`, then [shared_future_is_ready_link `this->is_ready()`] returns `true` and
[shared_future_get_state_link `this->get_state()`] returns __ready__.]]
[[Notes:] [`timed_wait()` is an ['interruption point]. `Duration` must be a type that meets the Boost.DateTime time duration requirements.]]
]
[endsect]
[//////////////////////////////////////////////////////////]
[section:timed_wait_absolute Member function `timed_wait()`]
bool timed_wait(boost::system_time const& wait_timeout);
[variablelist
[[Effects:] [If `*this` is associated with a shared state, waits until the result is ready, or the time point specified by
`wait_timeout` has passed. If the result is not ready on entry, and the result has a ['wait callback] set, that callback is invoked
prior to waiting.]]
[[Returns:] [`true` if `*this` is associated with a shared state, and that result is ready before the specified time has
passed, `false` otherwise.]]
[[Throws:] [
- __future_uninitialized__ if `*this` is not associated with a shared state.
- __thread_interrupted__ if the result associated with `*this` is not ready at the point of the call, and the current thread is interrupted.
- Any exception thrown by the ['wait callback] if such a callback is called.]]
[[Postconditions:] [If this call returned `true`, then [shared_future_is_ready_link `this->is_ready()`] returns `true` and
[shared_future_get_state_link `this->get_state()`] returns __ready__.]]
[[Notes:] [`timed_wait()` is an ['interruption point].]]
]
[endsect]
[/////////////////////////////////////////////]
[section:wait_for Member function `wait_for()`]
template <class Rep, class Period>
future_status wait_for(const chrono::duration<Rep, Period>& rel_time) const;
[variablelist
[[Effects:] [If `*this` is associated with a shared state, waits until the result is ready, or the time specified by
`wait_duration` has elapsed. If the result is not ready on entry, and the result has a ['wait callback] set, that callback is
invoked prior to waiting.]]
[[Returns:] [
- `future_status::deferred` if the shared state contains a deferred function. (Not implemented yet)
- `future_status::ready` if the shared state is ready.
- `future_status::timeout` if the function is returning because the relative timeout specified by `rel_time` has expired.
]]
[[Throws:] [
- __future_uninitialized__ if `*this` is not associated with a shared state.
- __thread_interrupted__ if the result associated with `*this` is not ready at the point of the call, and the current thread is interrupted.
- Any exception thrown by the ['wait callback] if such a callback is called.]]
[[Postconditions:] [If this call returned `true`, then [shared_future_is_ready_link `this->is_ready()`] returns `true` and
[shared_future_get_state_link `this->get_state()`] returns __ready__.]]
[[Notes:] [`timed_wait()` is an ['interruption point]. `Duration` must be a type that meets the Boost.DateTime time duration requirements.]]
]
[endsect]
[/////////////////////////////////////////////////]
[section:wait_until Member function `wait_until()`]
template <class Clock, class Duration>
future_status wait_until(const chrono::time_point<Clock, Duration>& abs_time) const;
[variablelist
[[Effects:] [If `*this` is associated with a shared state, waits until the result is ready, or the time point specified by
`wait_timeout` has passed. If the result is not ready on entry, and the result has a ['wait callback] set, that callback is invoked
prior to waiting.]]
[[Returns:] [
- `future_status::deferred` if the shared state contains a deferred function. (Not implemented yet)
- `future_status::ready` if the shared state is ready.
- `future_status::timeout` if the function is returning because the absolute timeout specified by `absl_time` has reached.
]]
[[Throws:] [
- __future_uninitialized__ if `*this` is not associated with a shared state.
- __thread_interrupted__ if the result associated with `*this` is not ready at the point of the call, and the current thread is interrupted.
- Any exception thrown by the ['wait callback] if such a callback is called.
]]
[[Postconditions:] [If this call returned `true`, then [shared_future_is_ready_link `this->is_ready()`] returns `true` and
[shared_future_get_state_link `this->get_state()`] returns __ready__.]]
[[Notes:] [`timed_wait()` is an ['interruption point].]]
]
[endsect]
[///////////////////////////////////////]
[section:valid Member function `valid()`]
bool valid() const noexcept;
[variablelist
[[Returns:] [`true` if `*this` is associated with a shared state, `false`
otherwise.]]
[[Throws:] [Nothing.]]
]
[endsect]
[///////////////////////////////////////////////////////]
[section:is_ready Member function `is_ready()` EXTENSION]
bool is_ready() const;
[variablelist
[[Returns:] [`true` if `*this` is associated with a shared state, and that result is ready for retrieval, `false`
otherwise.]]
[[Throws:] [Whatever `mutex::lock()/mutex::unlock()` can throw.]]
]
[endsect]
[/////////////////////////////////////////////////////////]
[section:has_value Member function `has_value()` EXTENSION]
bool has_value() const;
[variablelist
[[Returns:] [`true` if `*this` is associated with a shared state, that result is ready for retrieval, and the result is a
stored value, `false` otherwise.]]
[[Throws:] [Whatever `mutex::lock()/mutex::unlock()` can throw.]]
]
[endsect]
[/////////////////////////////////////////////////////////////////]
[section:has_exception Member function `has_exception()` EXTENSION]
bool has_exception() const;
[variablelist
[[Returns:] [`true` if `*this` is associated with a shared state, that result is ready for retrieval, and the result is a
stored exception, `false` otherwise.]]
[[Throws:] [Whatever `mutex::lock()/mutex::unlock()` can throw.]]
]
[endsect]
[/////////////////////////////////////////////////////////////////]
[section:get_exception_ptr Member function `get_exception_ptr()` EXTENSION]
exception_ptr get_exception_ptr();
[variablelist
[[Effects:] [If `*this` is associated with a shared state, waits until the result is ready. If the result is not ready on
entry, and the result has a ['wait callback] set, that callback is invoked prior to waiting.]]
[[Returns:] [an exception_ptr, storing or not an exception.]]
[[Throws:] [Whatever `mutex::lock()/mutex::unlock()` can throw.]]
]
[endsect]
[/////////////////////////////////////////////////////////]
[section:get_state Member function `get_state()` EXTENSION]
future_state::state get_state();
[variablelist
[[Effects:] [Determine the state of the shared state associated with `*this`, if any.]]
[[Returns:] [__uninitialized__ if `*this` is not associated with a shared state. __ready__ if the shared state
associated with `*this` is ready for retrieval, __waiting__ otherwise.]]
[[Throws:] [Whatever `mutex::lock()/mutex::unlock()` can throw.]]
]
[endsect]
[///////////////////////////////////////////////]
[section:then Member function `then()` EXTENSION]
template<typename F>
__unique_future__<typename boost::result_of<F(shared_future)>::type>
then(F&& func) const; // EXTENSION
template<typename Ex, typename F>
__unique_future__<typename boost::result_of<F(shared_future)>::type>
then(Ex& executor, F&& func) const; // EXTENSION
template<typename F>
__unique_future__<typename boost::result_of<F(shared_future)>::type>
then(launch policy, F&& func) const; // EXTENSION
[warning These functions are experimental and subject to change in future versions.
There are not too much tests yet, so it is possible that you can find out some trivial bugs :(]
[note These functions are based on the [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3634.pdf [*N3634 - Improvements to std::future<T> and related APIs]] C++1y proposal by N. Gustafsson, A. Laksberg, H. Sutter, S. Mithani.]
[variablelist
[[Notes:] [The three functions differ only by input parameters. The first only takes a callable object which accepts a
shared_future object as a parameter. The second function takes an executor as the first parameter and a callable object as
the second parameter. The third function takes a launch policy as the first parameter and a callable object as the
second parameter.]]
[[Requires:] [`INVOKE(DECAY_COPY (std::forward<F>(func)), *this)` shall be a valid expression.]]
[[Effects:] [
All the functions create a shared state that is associated with the returned future object. Additionally,
- When the object's shared state is ready, the continuation
`INVOKE(DECAY_COPY(std::forward<F>(func)), *this)` is called depending on the overload (see below) with the call to DECAY_COPY() being evaluated in the thread that called then.
- Any value returned from the continuation is stored as the result in the shared state of the resulting `future`.
Any exception propagated from the execution of the continuation is stored as the exceptional result in the shared state of the resulting `future`.
The continuation launches according to the specified policy or executor or noting.
- When the launch policy is `launch::none` the continuation is called on an unspecified thread of execution.
- When the launch policy is `launch::async` the continuation is called on a new thread of execution.
- When the launch policy is `launch::deferred` the continuation is called on demand.
- When the launch policy is `launch::executor` the continuation is called on one of the thread of execution of the executor.
- When the launch policy is `launch::inherit` the continuation inherits the parent's launch policy or executor.
- When the executor or launch policy is not provided (first overload) is if as if launch::none was specified.
- When the executor is provided (second overload) the continuation is called on one of the thread of execution of the executor.
- If the parent has a policy of `launch::deferred` and the continuation does not have a specified launch policy
executor, then the parent is filled by immediately calling `.wait()`, and the policy of the antecedent is
`launch::deferred`.
]]
[[Returns:] [An object of type `__unique_future__<typename boost::result_of<F(shared_future)>` that refers to the shared state created by the continuation.]]
[[Notes:] [
- Note that nested futures are not implicitly unwrapped yet. This could be subject to change in future versions.
- The returned futures behave as the ones returned from boost::async, the destructor of the future object returned from then will block. This could be subject to change in future versions.
]]
[[Postconditions:] [
- The future object is moved to the parameter of the continuation function .
- `valid() == true` on original `shared_future`; `valid() == true` on the `future` returned from then.
[/- In case of implicit unwrapping, the validity of the `future` returned from `then` cannot be established until after the completion of the functor passed into `then`. In such case, the resulting `future` becomes ready with an exception of type `future_error`, with an error code of `future_errc::broken_promise`. ]
]]
]
[endsect]
[endsect]
[////////////////////////////////////////]
[section:promise `promise` class template]
template <typename R>
class promise
{
public:
typedef R value_type; // EXTENSION
promise();
template <class Allocator>
promise(allocator_arg_t, Allocator a);
promise & operator=(promise const& rhs) = delete;
promise(promise const& rhs) = delete;
~promise();
// Move support
promise(promise && rhs) noexcept;;
promise & operator=(promise&& rhs) noexcept;;
void swap(promise& other) noexcept;
// Result retrieval
__unique_future__<R> get_future();
// Set the value
void set_value(see below);
void set_exception(boost::exception_ptr e);
template <typename E>
void set_exception(E e); // EXTENSION
// setting the result with deferred notification
void set_value_at_thread_exit(see below);
void set_exception_at_thread_exit(exception_ptr p);
template <typename E>
void set_exception_at_thread_exit(E p); // EXTENSION
template<typename F>
void set_wait_callback(F f); // EXTENSION
void set_value_deferred(see below); // EXTENSION
void set_exception_deferred(exception_ptr p); // EXTENSION
template <typename E>
void set_exception_deferred(E e); // EXTENSION
void notify_deferred(); // EXTENSION
};
[///////////////////////////////////////////////]
[section:default_constructor Default Constructor]
promise();
[variablelist
[[Effects:] [Constructs a new __promise__ with no associated result.]]
[[Throws:] [Nothing.]]
]
[endsect]
[///////////////////////////////////////////////]
[section:alloc_constructor Allocator Constructor]
template <class Allocator>
promise(allocator_arg_t, Allocator a);
[variablelist
[[Effects:] [Constructs a new __promise__ with no associated result using the allocator `a`.]]
[[Throws:] [Nothing.]]
[[Notes:] [Available only if BOOST_THREAD_FUTURE_USES_ALLOCATORS is defined.]]
]
[endsect]
[/////////////////////////////////////////]
[section:move_constructor Move Constructor]
promise(promise && other);
[variablelist
[[Effects:] [Constructs a new __promise__, and transfers ownership of the result associated with `other` to `*this`, leaving `other`
with no associated result.]]
[[Throws:] [Nothing.]]
[[Notes:] [If the compiler does not support rvalue-references, this is implemented using the boost.thread move emulation.]]
]
[endsect]
[////////////////////////////////////////////////]
[section:move_assignment Move Assignment Operator]
promise& operator=(promise && other);
[variablelist
[[Effects:] [Transfers ownership of the result associated with `other` to `*this`, leaving `other` with no associated result. If there
was already a result associated with `*this`, and that result was not ['ready], sets any futures associated with that result to
['ready] with a __broken_promise__ exception as the result. ]]
[[Throws:] [Nothing.]]
[[Notes:] [If the compiler does not support rvalue-references, this is implemented using the boost.thread move emulation.]]
]
[endsect]
[/////////////////////////////]
[section:destructor Destructor]
~promise();
[variablelist
[[Effects:] [Destroys `*this`. If there was a result associated with `*this`, and that result is not ['ready], sets any futures
associated with that task to ['ready] with a __broken_promise__ exception as the result.]]
[[Throws:] [Nothing.]]
]
[endsect]
[/////////////////////////////////////////////////]
[section:get_future Member Function `get_future()`]
__unique_future__<R> get_future();
[variablelist
[[Effects:] [If `*this` was not associated with a result, allocate storage for a new shared state and associate it with
`*this`. Returns a __unique_future__ associated with the result associated with `*this`. ]]
[[Throws:] [__future_already_retrieved__ if the future associated with the task has already been retrieved. `std::bad_alloc` if any
memory necessary could not be allocated.]]
]
[endsect]
[///////////////////////////////////////////////]
[section:set_value Member Function `set_value()`]
void set_value(R&& r);
void set_value(const R& r);
void promise<R&>::set_value(R& r);
void promise<void>::set_value();
[variablelist
[[Effects:] [
- If BOOST_THREAD_PROVIDES_PROMISE_LAZY is defined and if `*this` was not associated with a result, allocate storage for a new shared state and associate it with `*this`.
- Store the value `r` in the shared state associated with `*this`. Any threads blocked waiting for the asynchronous
result are woken.
]]
[[Postconditions:] [All futures waiting on the shared state are ['ready] and __unique_future_has_value__ or
__shared_future_has_value__ for those futures shall return `true`.]]
[[Throws:] [
- __promise_already_satisfied__ if the result associated with `*this` is already ['ready].
- __broken_promise__ if `*this` has no shared state.
- `std::bad_alloc` if the memory required for storage of the result cannot be allocated.
- Any exception thrown by the copy or move-constructor of `R`.]]
]
[endsect]
[///////////////////////////////////////////////////////]
[section:set_exception Member Function `set_exception()`]
void set_exception(boost::exception_ptr e);
template <typename E>
void set_exception(E e); // EXTENSION
[variablelist
[[Effects:] [
- If BOOST_THREAD_PROVIDES_PROMISE_LAZY is defined and if `*this` was not associated with a result, allocate storage for a new shared state and associate it with
`*this`.
- Store the exception `e` in the shared state associated with `*this`. Any threads blocked waiting for the asynchronous
result are woken.]]
[[Postconditions:] [All futures waiting on the shared state are ['ready] and __unique_future_has_exception__ or
__shared_future_has_exception__ for those futures shall return `true`.]]
[[Throws:] [
- __promise_already_satisfied__ if the result associated with `*this` is already ['ready].
- __broken_promise__ if `*this` has no shared state.
- `std::bad_alloc` if the memory required for storage of the result cannot be allocated.
]]
]
[endsect]
[/////////////////////////////////////////////////////////////////////////////]
[section:set_value_at_thread_exit Member Function `set_value_at_thread_exit()`]
void set_value_at_thread_exit(R&& r);
void set_value_at_thread_exit(const R& r);
void promise<R&>::set_value_at_thread_exit(R& r);
void promise<void>::set_value_at_thread_exit();
[variablelist
[[Effects:] [
Stores the value r in the shared state without making that state ready immediately.
Schedules that state to be made ready when the current thread exits, after all objects of thread storage duration
associated with the current thread have been destroyed.]]
[[Postconditions:] [the result associated with `*this` is set as deferred]]
[[Throws:] [
- __promise_already_satisfied__ if the result associated with `*this` is already ['ready] or deferred.
- __broken_promise__ if `*this` has no shared state.
- `std::bad_alloc` if the memory required for storage of the result cannot be allocated.
- Any exception thrown by the copy or move-constructor of `R`.
]]
]
[endsect]
[/////////////////////////////////////////////////////////////////////////////////////]
[section:set_exception_at_thread_exit Member Function `set_exception_at_thread_exit()`]
void set_exception_at_thread_exit(boost::exception_ptr e);
template <typename E>
void set_exception_at_thread_exit(E p); // EXTENSION
[variablelist
[[Effects:] [
Stores the exception pointer p in the shared state without making that state ready immediately.
Schedules that state to be made ready when the current thread exits, after all objects of thread storage duration
associated with the current thread have been destroyed.]]
[[Postconditions:] [the result associated with `*this` is set as deferred]]
[[Throws:] [
- __promise_already_satisfied__ if the result associated with `*this` is already ['ready] or deferred.
- __broken_promise__ if `*this` has no shared state.
- `std::bad_alloc` if the memory required for storage of the result cannot be allocated.
]]
]
[endsect]
[/////////////////////////////////////////////////////////////////////////]
[section:set_wait_callback Member Function `set_wait_callback()` EXTENSION]
template<typename F>
void set_wait_callback(F f);
[variablelist
[[Preconditions:] [The expression `f(t)` where `t` is a lvalue of type __promise__ shall be well-formed. Invoking a copy of
`f` shall have the same effect as invoking `f`]]
[[Effects:] [Store a copy of `f` with the shared state associated with `*this` as a ['wait callback]. This will replace any
existing wait callback store alongside that result. If a thread subsequently calls one of the wait functions on a __unique_future__
or __shared_future__ associated with this result, and the result is not ['ready], `f(*this)` shall be invoked.]]
[[Throws:] [`std::bad_alloc` if memory cannot be allocated for the required storage.]]
]
[endsect]
[///////////////////////////////////////////////]
[section:set_value Member Function `set_value_deferred()` EXTENSION]
void set_value_deferred(R&& r);
void set_value_deferred(const R& r);
void promise<R&>:: set_value_deferred(R& r);
void promise<void>:: set_value_deferred();
[variablelist
[[Effects:] [
- If BOOST_THREAD_PROVIDES_PROMISE_LAZY is defined and if `*this` was not associated with a result, allocate storage for a new shared state and associate it with `*this`.
- Stores the value `r` in the shared state without making that state ready immediately. Threads blocked waiting for the asynchronous result are not woken. They will be woken only when `notify_deferred` is called.
]]
[[Postconditions:] [the result associated with `*this` is set as deferred]]
[[Throws:] [
- __promise_already_satisfied__ if the result associated with `*this` is already ['ready] or deferred.
- __broken_promise__ if `*this` has no shared state.
- `std::bad_alloc` if the memory required for storage of the result cannot be allocated.
- Any exception thrown by the copy or move-constructor of `R`.]]
]
[endsect]
[///////////////////////////////////////////////////////]
[section:set_exception Member Function `set_exception_deferred()` EXTENSION]
void set_exception_deferred(boost::exception_ptr e);
template <typename E>
void set_exception_deferred(E e); // EXTENSION
[variablelist
[[Effects:] [
- If BOOST_THREAD_PROVIDES_PROMISE_LAZY is defined and if `*this` was not associated with a result, allocate storage for a new shared state and associate it with `*this`.
- Store the exception `e` in the shared state associated with `*this`without making that state ready immediately. Threads blocked waiting for the asynchronous result are not woken. They will be woken only when `notify_deferred` is called.]]
[[Postconditions:] [the result associated with `*this` is set as deferred]]
[[Throws:] [
- __promise_already_satisfied__ if the result associated with `*this` is already ['ready] or deferred.
- __broken_promise__ if `*this` has no shared state.
- `std::bad_alloc` if the memory required for storage of the result cannot be allocated.
]]
]
[endsect]
[///////////////////////////////////////////////]
[section:set_value Member Function `notify_deferred()` EXTENSION]
[variablelist
[[Effects:] [
Any threads blocked waiting for the asynchronous result are woken.
]]
[[Postconditions:] [All futures waiting on the shared state are ['ready] and __unique_future_has_value__ or
__shared_future_has_value__ for those futures shall return `true`.]]
[[Postconditions:] [the result associated with `*this` is ready.]]
]
[endsect]
[endsect]
[////////////////////////////////////////////////////]
[section:packaged_task `packaged_task` class template]
template<typename S>
class packaged_task;
template<typename R
, class... ArgTypes
>
class packaged_task<R(ArgTypes)>
{
public:
packaged_task(packaged_task const&) = delete;
packaged_task& operator=(packaged_task const&) = delete;
// construction and destruction
packaged_task() noexcept;
explicit packaged_task(R(*f)(ArgTypes...));
template <class F>
explicit packaged_task(F&& f);
template <class Allocator>
packaged_task(allocator_arg_t, Allocator a, R(*f)(ArgTypes...));
template <class F, class Allocator>
packaged_task(allocator_arg_t, Allocator a, F&& f);
~packaged_task()
{}
// move support
packaged_task(packaged_task&& other) noexcept;
packaged_task& operator=(packaged_task&& other) noexcept;
void swap(packaged_task& other) noexcept;
bool valid() const noexcept;
// result retrieval
__unique_future__<R> get_future();
// execution
void operator()(ArgTypes... );
void make_ready_at_thread_exit(ArgTypes...);
void reset();
template<typename F>
void set_wait_callback(F f); // EXTENSION
};
[/////////////////////////////////////////]
[section:task_constructor Task Constructor]
packaged_task(R(*f)(ArgTypes...));
template<typename F>
packaged_task(F&&f);
[variablelist
[[Preconditions:] [`f()` is a valid expression with a return type convertible to `R`. Invoking a copy of `f` must behave the same
as invoking `f`.]]
[[Effects:] [Constructs a new __packaged_task__ with `boost::forward<F>(f)` stored as the associated task.]]
[[Throws:] [
- Any exceptions thrown by the copy (or move) constructor of `f`.
- `std::bad_alloc` if memory for the internal data structures could not be allocated.
]]
[[Notes:] [The R(*f)(ArgTypes...)) overload to allow passing a function without needing to use `&`.]]
[[Remark:] [This constructor doesn't participate in overload resolution if decay<F>::type is the same type as boost::packaged_task<R>.]]
]
[endsect]
[///////////////////////////////////////////////]
[section:alloc_constructor Allocator Constructor]
template <class Allocator>
packaged_task(allocator_arg_t, Allocator a, R(*f)(ArgTypes...));
template <class F, class Allocator>
packaged_task(allocator_arg_t, Allocator a, F&& f);
[variablelist
[[Preconditions:] [`f()` is a valid expression with a return type convertible to `R`. Invoking a copy of `f` shall behave the same
as invoking `f`.]]
[[Effects:] [Constructs a new __packaged_task with `boost::forward<F>(f)` stored as the associated task using the allocator `a`.]]
[[Throws:] [Any exceptions thrown by the copy (or move) constructor of `f`. `std::bad_alloc` if memory for the internal data
structures could not be allocated.]]
[[Notes:] [Available only if BOOST_THREAD_FUTURE_USES_ALLOCATORS is defined.]]
[[Notes:] [The R(*f)(ArgTypes...)) overload to allow passing a function without needing to use `&`.]]
]
[endsect]
[/////////////////////////////////////////]
[section:move_constructor Move Constructor]
packaged_task(packaged_task && other);
[variablelist
[[Effects:] [Constructs a new __packaged_task__, and transfers ownership of the task associated with `other` to `*this`, leaving `other`
with no associated task.]]
[[Throws:] [Nothing.]]
[[Notes:] [If the compiler does not support rvalue-references, this is implemented using the boost.thread move emulation.]]
]
[endsect]
[////////////////////////////////////////////////]
[section:move_assignment Move Assignment Operator]
packaged_task& operator=(packaged_task && other);
[variablelist
[[Effects:] [Transfers ownership of the task associated with `other` to `*this`, leaving `other` with no associated task. If there
was already a task associated with `*this`, and that task has not been invoked, sets any futures associated with that task to
['ready] with a __broken_promise__ exception as the result. ]]
[[Throws:] [Nothing.]]
[[Notes:] [If the compiler does not support rvalue-references, this is implemented using the boost.thread move emulation.]]
]
[endsect]
[/////////////////////////////]
[section:destructor Destructor]
~packaged_task();
[variablelist
[[Effects:] [Destroys `*this`. If there was a task associated with `*this`, and that task has not been invoked, sets any futures
associated with that task to ['ready] with a __broken_promise__ exception as the result.]]
[[Throws:] [Nothing.]]
]
[endsect]
[/////////////////////////////////////////////////]
[section:get_future Member Function `get_future()`]
__unique_future__<R> get_future();
[variablelist
[[Effects:] [Returns a __unique_future__ associated with the result of the task associated with `*this`. ]]
[[Throws:] [__task_moved__ if ownership of the task associated with `*this` has been moved to another instance of
__packaged_task__. __future_already_retrieved__ if the future associated with the task has already been retrieved.]]
]
[endsect]
[////////////////////////////////////////////////////]
[section:call_operator Member Function `operator()()`]
void operator()();
[variablelist
[[Effects:] [Invoke the task associated with `*this` and store the result in the corresponding future. If the task returns normally,
the return value is stored as the shared state, otherwise the exception thrown is stored. Any threads blocked waiting for the
shared state associated with this task are woken.]]
[[Postconditions:] [All futures waiting on the shared state are ['ready]]]
[[Throws:] [
- __task_moved__ if ownership of the task associated with `*this` has been moved to another instance of __packaged_task__.
- __task_already_started__ if the task has already been invoked.]]
]
[endsect]
[///////////////////////////////////////////////////////////////////////////////]
[section:make_ready_at_thread_exit Member Function `make_ready_at_thread_exit()`]
void make_ready_at_thread_exit(ArgTypes...);
[variablelist
[[Effects:] [Invoke the task associated with `*this` and store the result in the corresponding future. If the task returns normally,
the return value is stored as the shared state, otherwise the exception thrown is stored.
In either case, this is done without making that state ready immediately.
Schedules the shared state to be made ready when the current thread exits, after all objects of thread storage
duration associated with the current thread have been destroyed.]]
[[Throws:] [
- __task_moved__ if ownership of the task associated with `*this` has been moved to another instance of __packaged_task__.
- __task_already_started__ if the task has already been invoked.
]]
]
[endsect]
[///////////////////////////////////////]
[section:reset Member Function `reset()`]
void reset();
[variablelist
[[Effects:] [Reset the state of the packaged_task so that it can be called again.]]
[[Throws:] [__task_moved__ if ownership of the task associated with `*this` has been moved to another instance of
__packaged_task__.]]
]
[endsect]
[/////////////////////////////////////////////////////////////////////////]
[section:set_wait_callback Member Function `set_wait_callback()` EXTENSION]
template<typename F>
void set_wait_callback(F f);
[variablelist
[[Preconditions:] [The expression `f(t)` where `t` is a lvalue of type __packaged_task__ shall be well-formed. Invoking a copy of
`f` shall have the same effect as invoking `f`]]
[[Effects:] [Store a copy of `f` with the task associated with `*this` as a ['wait callback]. This will replace any existing wait
callback store alongside that task. If a thread subsequently calls one of the wait functions on a __unique_future__ or
__shared_future__ associated with this task, and the result of the task is not ['ready], `f(*this)` shall be invoked.]]
[[Throws:] [__task_moved__ if ownership of the task associated with `*this` has been moved to another instance of
__packaged_task__.]]
]
[endsect]
[endsect]
[//////////////////////////////////////////////////////]
[section:decay_copy Non-member function `decay_copy()`]
template <class T>
typename decay<T>::type decay_copy(T&& v)
{
return boost::forward<T>(v);
}
[endsect]
[///////////////////////////////////////////]
[section:async Non-member function `async()`]
The function template async provides a mechanism to launch a function potentially in a new thread and
provides the result of the function in a future object with which it shares a shared state.
[heading Non-Variadic variant]
template <class F>
__unique_future__<typename result_of<typename decay<F>::type()>::type>
async(F&& f);
template <class F>
__unique_future__<typename result_of<typename decay<F>::type()>::type>
async(launch policy, F&& f);
template <class Executor, class F>
__unique_future__<typename result_of<typename decay<F>::type(typename decay<Args>::type...)>::type>
async(Executor &ex, F&& f, Args&&... args);
[variablelist
[[Requires:] [
``
decay_copy(boost::forward<F>(f))()
``
shall be a valid expression.
]]
[[Effects] [
The first function behaves the same as a call to the second function with a policy argument of
`launch::async | launch::deferred` and the same arguments for `F`.
The second and third functions create a shared state that is associated with the returned future object.
The further behavior of the second function depends on the policy argument as follows (if more than one of these conditions applies, the implementation may choose any of the corresponding policies):
- if `policy & launch::async` is non-zero - calls `decay_copy(boost::forward<F>(f))()` as if in a new thread of execution represented by a thread object with the calls to `decay_copy()` being evaluated in the thread that called `async`. Any return value is stored as the result in the shared state. Any exception propagated from the execution of `decay_copy(boost::forward<F>(f))()` is stored as the exceptional result in the shared state. The thread object is stored in the shared state and affects the behavior of any asynchronous return objects that reference that state.
- if `policy & launch::deferred` is non-zero - Stores `decay_copy(boost::forward<F>(f))` in the shared state. This copy of `f` constitute a deferred function. Invocation of the deferred function evaluates `boost::move(g)()` where `g` is the stored value of `decay_copy(boost::forward<F>(f))`. The shared state is not made ready until the function has completed. The first call to a non-timed waiting function on an asynchronous return object referring to this shared state shall invoke the deferred function in the thread that called the waiting function. Once evaluation of `boost::move(g)()` begins, the function is no longer considered deferred. (Note: If this policy is specified together with other policies, such as when using a policy value of `launch::async | launch::deferred`, implementations should defer invocation or the selection of the policy when no more concurrency can be effectively exploited.)
- if no valid launch policy is provided the behavior is undefined.
The further behavior of the third function is as follows:
- The Executor::submit() function is given a function<void ()> which calls `INVOKE (DECAY_COPY
(std::forward<F>(f)), DECAY_COPY (std::forward<Args>(args))...). The implementation of the executor
is decided by the programmer.
]]
[[Returns:] [An object of type `__unique_future__<typename result_of<typename decay<F>::type()>::type>` that refers to the shared state created by this call to `async`.]]
[[Synchronization:] [Regardless of the provided policy argument,
- the invocation of `async` synchronizes with the invocation of `f`. (Note: This statement applies even when the corresponding future object is moved to another thread.); and
- the completion of the function `f` is sequenced before the shared state is made ready. (Note: `f` might not be called at all, so its completion might never happen.)
If the implementation chooses the `launch::async` policy,
- a call to a non-timed waiting function on an asynchronous return object that shares the shared state created by this async call shall block until the associated thread has completed, as if joined, or else time out;
- the associated thread completion synchronizes with the return from the first function that successfully detects the ready status of the shared state or with the return from the last function that releases the shared state, whichever happens first.
]]
[[Throws:][`system_error` if policy is `launch::async` and the implementation is unable to start a new thread.
]]
[[Error conditions:] [
- `resource_unavailable_try_again` - if policy is `launch::async` and the system is unable to start a new thread.
]]
[[Remarks::] [The first signature shall not participate in overload resolution if `decay_t<F> is `boost::
launch` or `boost::is_executor<F>` is `true_type`.]]
]
[heading Variadic variant]
template <class F, class... Args>
__unique_future__<typename result_of<typename decay<F>::type(typename decay<Args>::type...)>::type>
async(F&& f, Args&&... args);
template <class F, class... Args>
__unique_future__<typename result_of<typename decay<F>::type(typename decay<Args>::type...)>::type>
async(launch policy, F&& f, Args&&... args);
template <class Executor, class F, class... Args>
__unique_future__<typename result_of<typename decay<F>::type(typename decay<Args>::type...)>::type>
async(Executor &ex, F&& f, Args&&... args);
[warning the variadic prototype is provided only on C++11 compilers supporting rvalue references, variadic templates, decltype and a standard library providing <tuple> (waiting for a boost::tuple that is move aware), and BOOST_THREAD_PROVIDES_SIGNATURE_PACKAGED_TASK is defined.]
[variablelist
[[Requires:] [
`F` and each `Ti` in `Args` shall satisfy the `MoveConstructible` requirements.
invoke (decay_copy (boost::forward<F>(f)), decay_copy (boost::forward<Args>(args))...)
shall be a valid expression.
]]
[[Effects:] [
- The first function behaves the same as a call to the second function with a policy argument of `launch::async | launch::deferred` and the same arguments for `F` and `Args`.
- The second function creates a shared state that is associated with the returned future object.
The further behavior of the second function depends on the policy argument as follows (if more than one of these conditions applies,
the implementation may choose any of the corresponding policies):
- if `policy & launch::async` is non-zero - calls `invoke(decay_copy(forward<F>(f)), decay_copy (forward<Args>(args))...)`
as if in a new thread of execution represented by a thread object with the calls to `decay_copy()` being evaluated in the thread that called `async`.
Any return value is stored as the result in the shared state.
Any exception propagated from the execution of `invoke(decay_copy(boost::forward<F>(f)), decay_copy (boost::forward<Args>(args))...)`
is stored as the exceptional result in the shared state. The thread object is stored in the shared state and
affects the behavior of any asynchronous return objects that reference that state.
- if `policy & launch::deferred` is non-zero - Stores `decay_copy(forward<F>(f))` and `decay_copy(forward<Args>(args))...` in the shared state.
These copies of `f` and `args` constitute a deferred function. Invocation of the deferred function evaluates
`invoke(move(g), move(xyz))` where `g` is the stored value of `decay_copy(forward<F>(f))` and `xyz` is the stored copy of `decay_copy(forward<Args>(args))...`.
The shared state is not made ready until the function has completed. The first call to a non-timed waiting function on
an asynchronous return object referring to this shared state shall invoke the deferred function in the thread that called the waiting function.
Once evaluation of `invoke(move(g), move(xyz))` begins, the function is no longer considered deferred.
- if no valid launch policy is provided the behaviour is undefined.
]]
[[Note:] [If this policy is specified together with other policies, such as when using a policy value of `launch::async | launch::deferred`,
implementations should defer invocation or the selection of the policy when no more concurrency can be effectively exploited.]]
[[Returns:] [An object of type `__unique_future__<typename result_of<typename decay<F>::type(typename decay<Args>::type...)>::type>`
that refers to the shared state created by this call to `async`.]]
[[Synchronization:] [Regardless of the provided policy argument,
- the invocation of async synchronizes with the invocation of `f`. (Note: This statement applies even when the corresponding future object is moved to another thread.); and
- the completion of the function `f` is sequenced before the shared state is made ready. (Note: f might not be called at all, so its completion might never happen.)
If the implementation chooses the `launch::async` policy,
- a call to a waiting function on an asynchronous return object that shares the shared state created by this async call
shall block until the associated thread has completed, as if joined, or else time out;
- the associated thread completion synchronizes with the return from the first function that successfully detects the ready status of the shared state or
with the return from the last function that releases the shared state, whichever happens first.
]]
[[Throws:] [`system_error` if policy is `launch::async` and the implementation is unable to start a new thread.
]]
[[Error conditions:][
- `resource_unavailable_try_again` - if policy is `launch::async` and the system is unable to start a new thread.
]]
[[Remarks:] [The first signature shall not participate in overload resolution if decay<F>::type is boost::launch.
]]
]
[endsect]
[/////////////////////////////////////////////////////////////////////]
[section:wait_for_any Non-member function `wait_for_any()` - EXTENSION]
template<typename Iterator>
Iterator wait_for_any(Iterator begin,Iterator end); // EXTENSION
template<typename F1,typename F2>
unsigned wait_for_any(F1& f1,F2& f2); // EXTENSION
template<typename F1,typename F2,typename F3>
unsigned wait_for_any(F1& f1,F2& f2,F3& f3); // EXTENSION
template<typename F1,typename F2,typename F3,typename F4>
unsigned wait_for_any(F1& f1,F2& f2,F3& f3,F4& f4); // EXTENSION
template<typename F1,typename F2,typename F3,typename F4,typename F5>
unsigned wait_for_any(F1& f1,F2& f2,F3& f3,F4& f4,F5& f5); // EXTENSION
[variablelist
[[Preconditions:] [The types `Fn` shall be specializations of
__unique_future__ or __shared_future__, and `Iterator` shall be a
forward iterator with a `value_type` which is a specialization of
__unique_future__ or __shared_future__.]]
[[Effects:] [Waits until at least one of the specified futures is ['ready].]]
[[Returns:] [The range-based overload returns an `Iterator` identifying the first future in the range that was detected as
['ready]. The remaining overloads return the zero-based index of the first future that was detected as ['ready] (first parameter =>
0, second parameter => 1, etc.).]]
[[Throws:] [__thread_interrupted__ if the current thread is interrupted. Any exception thrown by the ['wait callback] associated
with any of the futures being waited for. `std::bad_alloc` if memory could not be allocated for the internal wait structures.]]
[[Notes:] [`wait_for_any()` is an ['interruption point].]]
]
[endsect]
[/////////////////////////////////////////////////////////////////////]
[section:wait_for_all Non-member function `wait_for_all()` - EXTENSION]
template<typename Iterator>
void wait_for_all(Iterator begin,Iterator end); // EXTENSION
template<typename F1,typename F2>
void wait_for_all(F1& f1,F2& f2); // EXTENSION
template<typename F1,typename F2,typename F3>
void wait_for_all(F1& f1,F2& f2,F3& f3); // EXTENSION
template<typename F1,typename F2,typename F3,typename F4>
void wait_for_all(F1& f1,F2& f2,F3& f3,F4& f4); // EXTENSION
template<typename F1,typename F2,typename F3,typename F4,typename F5>
void wait_for_all(F1& f1,F2& f2,F3& f3,F4& f4,F5& f5); // EXTENSION
[variablelist
[[Preconditions:] [The types `Fn` shall be specializations of
__unique_future__ or __shared_future__, and `Iterator` shall be a
forward iterator with a `value_type` which is a specialization of
__unique_future__ or __shared_future__.]]
[[Effects:] [Waits until all of the specified futures are ['ready].]]
[[Throws:] [Any exceptions thrown by a call to `wait()` on the specified futures.]]
[[Notes:] [`wait_for_all()` is an ['interruption point].]]
]
[endsect]
[/////////////////////////////////////////////////////////////////////]
[section:when_all Non-member function `when_all()` - EXTENSION]
template <class InputIterator>
future<std::vector<typename InputIterator::value_type::value_type>>
when_all(InputIterator first, InputIterator last);
template <typename... FutTypes>
future<std::tuple<decay_t<FutTypes>...> when_all(FutTypes&&... futures);
[variablelist
[[Requires:] [
- For the first overload, `InputIterator`'s value type shall be convertible to `future<R>` or `shared_future<R>`.
All `R` types must be the same. If any of the `future<R>` or `shared_future<R>` objects are in invalid state (i.e. `valid() == false`), the behavior is undefined.
- For the second overload, `FutTypes` is of type `future<R>` or `shared_future<R>`. The effect of calling `when_all` on a `future` or a `shared_future` object for which `valid() == false` is undefined.
]]
[[Notes:] [
- There are two variations of `when_all`. The first version takes a pair of `InputIterators`. The second takes any arbitrary number of `future<R0>` and `shared_future<R1>` objects, where `R0` and `R1` need not be the same type.
- Calling the first signature of `when_all` where `InputIterator` first equals last, returns a future with an empty `vector` that is immediately ready.
- Calling the second signature of `when_all` with no arguments returns a future<tuple<>> that is immediately ready.
]]
[[Effects:] [
- If any of the futures supplied to a call to `when_all` refer to deferred tasks that have not started execution, those tasks are executed before the call to `when_all` returns. Once all such tasks have been executed, the call to `when_all` returns immediately.
- The call to `when_all` does not wait for non-deferred tasks, or deferred tasks that have already started executing elsewhere, to complete before returning.
- Once all the `future`s/`shared_future`s supplied to the call to `when_all` are ready, the `future`s/`shared_future`s are moved/copied into the associated state of the future returned from the call to `when_all`, preserving the order of the futures supplied to `when_all`.
- The collection is then stored as the result in a newly created shared state.
- A new future object that refers to the shared state is created. The exact type of the future is further described below.
- The `future` returned by `when_all` will not throw an exception when calling `wait()` or `get()`, but the futures held in the output collection may.
]]
[[Returns:] [
- `future<tuple<>>` if `when_all` is called with zero arguments.
- `future<vector<future<R>>>` if the input cardinality is unknown at compile and the iterator pair yields `future<R>`. The order of the futures in the output vector will be the same as given by the input iterator.
- `future<vector<shared_future<R>>>` if the input cardinality is unknown at compile time and the iterator pair yields `shared_future<R>`. The order of the futures in the output vector will be the same as given by the input iterator.
- `future<tuple<decay_t<FutTypes>...>>` if inputs are fixed in number.
]]
[[Postconditions:] [
- All input futures valid() == false.
- All input shared future valid() == true.
- valid() == true.
]]
]
[endsect]
[/////////////////////////////////////////////////////////////////////]
[section:when_any Non-member function `when_any()` - EXTENSION]
template <class InputIterator>
future<std::vector<typename InputIterator::value_type::value_type>>
when_any(InputIterator first, InputIterator last);
template <typename... FutTypes>
future<std::tuple<decay_t<FutTypes>...>
when_any(FutTypes&&... futures);
[variablelist
[[Requires:] [
- For the first overload, `InputIterator`'s value type shall be convertible to `future<R>` or `shared_future<R>`. All `R` types must be the same. If any of the `future<R>` or `shared_future<R>` objects are in invalid state (i.e. `valid() == false`), the behavior is undefined.
- For the second overload, `FutTypes` is of type `future<R>` or `shared_future<R>`. The effect of calling `when_any` on a `future` or a `shared_future` object for which `valid() == false is undefined`.
]]
[[Notes:] [
- There are two variations of `when_any `. The first version takes a pair of `InputIterators`. The second takes any arbitrary number of `future<R0>` and `shared_future<R1>` objects, where `R0` and `R1` need not be the same type.
- Calling the first signature of `when_any ` where `InputIterator` first equals last, returns a future with an empty `vector` that is immediately ready.
- Calling the second signature of `when_any` with no arguments returns a future<tuple<>> that is immediately ready.
]]
[[Effects:] [
- Each of the futures supplied to `when_any` is checked in the order supplied. If a given future is ready, then no further futures are checked, and the call to `when_any` returns immediately. If a given future refers to a deferred task that has not yet started execution, then no further futures are checked, that task is executed, and the call to `when_any` then returns immediately.
- The call to `when_any` does not wait for non-deferred tasks, or deferred tasks that have already started executing elsewhere, to complete before returning.
- Once at least one of the futures supplied to the call to `when_any` are ready, the futures are moved into the associated state of the future returned from the call to `when_any`, preserving the order of the futures supplied to `when_any`. That future is then ready.
- The collection is then stored as the result in a newly created shared state.
- A new future object that refers to the shared state is created. The exact type of the future is further described below.
- The future returned by `when_any` will not throw an exception when calling `wait()` or `get()`, but the futures held in the output collection may.
]]
[[Returns:] [
- `future<tuple<>>` if `when_any ` is called with zero arguments.
- `future<vector<future<R>>>` if the input cardinality is unknown at compile and the iterator pair yields `future<R>`. The order of the futures in the output vector will be the same as given by the input iterator.
- `future<vector<shared_future<R>>>` if the input cardinality is unknown at compile time and the iterator pair yields `shared_future<R>`. The order of the futures in the output vector will be the same as given by the input iterator.
- `future<tuple<decat_t<FutTypes>...>>` if inputs are fixed in number.
]]
[[Postconditions:] [
- All input futures valid() == false.
- All input shared_futures valid() == true.
- valid() == true.
]]
]
[endsect]
[/////////////////////////////////////////////////////////////////////////////]
[section:make_ready_future Non-member function `make_ready_future()` EXTENSION]
template <typename T>
future<V> make_ready_future(T&& value); // EXTENSION
future<void> make_ready_future(); // EXTENSION
template <typename T>
future<T> make_ready_future(exception_ptr ex); // DEPRECATED
template <typename T, typename E>
future<T> make_ready_future(E ex); // DEPRECATED
[variablelist
[[Remark:][
where `V` is determined as follows: Let `U` be `decay_t<T>`. Then `V` is `X&`
if `U` equals `reference_wrapper<X>`, otherwise `V` is `U`.
]]
[[Effects:] [
- value prototype: The value that is passed into the function is moved to the shared state of the returned future if it is an rvalue.
Otherwise the value is copied to the shared state of the returned future.
- exception: The exception that is passed into the function is copied to the shared state of the returned future.
.]]
[[Returns:] [
- a ready future with the value set with `value`
- a ready future with the exception set with `ex`
- a ready future<void> with the value set (void).
]]
[[Postcondition:] [
- Returned future, valid() == true
- Returned future, is_ready() = true
- Returned future, has_value() = true or has_exception() depending on the prototype.
]]
]
[endsect]
[/////////////////////////////////////////////////////////////////////////////]
[section:make_exceptional_future Non-member function `make_exceptional_future()` EXTENSION]
exceptional_ptr make_exceptional_future(exception_ptr ex); // EXTENSION
template <typename E>
exceptional_ptr make_exceptional_future(E ex); // EXTENSION
exceptional_ptr make_exceptional_future(); // EXTENSION
[variablelist
[[Effects:] [
The exception that is passed in to the function or the current exception if no parameter is given is moved into the returned `exceptional_ptr` if it is an rvalue. Otherwise the exception is copied into the returned `exceptional_ptr`.
]]
[[Returns:] [
An exceptional_ptr instance implicitly convertible to a future<T>
]]
]
[endsect]
[//////////////////////////////////////////////////////////////////]
[section:make_future Non-member function `make_future()` DEPRECATED]
template <typename T>
future<typename decay<T>::type> make_future(T&& value); // DEPRECATED
future<void> make_future(); // DEPRECATED
[variablelist
[[Effects:] [
The value that is passed into the function is moved to the shared state of the returned function if it is an rvalue.
Otherwise the value is copied to the shared state of the returned function.
.]]
[[Returns:] [
- future<T>, if function is given a value of type T
- future<void>, if the function is not given any inputs.
]]
[[Postcondition:] [
- Returned future<T>, valid() == true
- Returned future<T>, is_ready() = true
]]
[[See:] [`make_ready_future()`]]
]
[endsect]
[////////////////////////////////////////////////////////////////////////////////]
[section:make_shared_future Non-member function `make_shared_future()` DEPRECATED]
template <typename T>
shared_future<typename decay<T>::type> make_shared_future(T&& value); // DEPRECATED
shared_future<void> make_shared_future(); // DEPRECATED
[variablelist
[[Effects:] [
The value that is passed in to the function is moved to the shared state of the returned function if it is an rvalue.
Otherwise the value is copied to the shared state of the returned function.
.]]
[[Returns:] [
- shared_future<T>, if function is given a value of type T
- shared_future<void>, if the function is not given any inputs.
]]
[[Postcondition:] [
- Returned shared_future<T>, valid() == true
- Returned shared_future<T>, is_ready() = true
]]
[[See:] [`make_ready_future()` and `future<>::share()`]]
]
[endsect]
[endsect]