future.hpp#

See Public API for a list of names and headers that are part of the public HPX API.

Defines

HPX_MAKE_EXCEPTIONAL_FUTURE(T, errorcode, f, msg)#

namespace hpx

Top level HPX namespace.

Functions

template<typename R, typename U> hpx::future<R> make_future(hpx::future<U> &&f)#: Converts any future of type U to any other future of type R based on an existing conversion path from U to R.

template<typename R, typename U, typename Conv> hpx::future<R> make_future(hpx::future<U> &&f, Conv &&conv)#: Converts any future of type U to any other future of type R based on a given conversion function: R conv(U).

template<typename R, typename U> hpx::future<R> make_future(hpx::shared_future<U> f)#: Converts any shared_future of type U to any other future of type R based on an existing conversion path from U to R.

template<typename R, typename U, typename Conv> hpx::future<R> make_future(hpx::shared_future<U> f, Conv &&conv)#: Converts any future of type U to any other future of type R based on an existing conversion path from U to R.

template<typename R> hpx::shared_future<R> make_shared_future(hpx::future<R> &&f) noexcept#: Converts any future or shared_future of type T to a corresponding shared_future of type T.

template<typename R> hpx::shared_future<R> &make_shared_future(hpx::shared_future<R> &f) noexcept#: Converts any future or shared_future of type T to a corresponding shared_future of type T.

template<typename R> hpx::shared_future<R> &&make_shared_future(hpx::shared_future<R> &&f) noexcept#: Converts any future or shared_future of type T to a corresponding shared_future of type T.

template<typename R> hpx::shared_future<R> const &make_shared_future(hpx::shared_future<R> const &f) noexcept#: Converts any future or shared_future of type T to a corresponding shared_future of type T.

template<typename T, typename Allocator, typename ...Ts> std::enable_if_t<std::is_constructible_v<T, Ts&&...> || std::is_void_v<T>, future<T>> make_ready_future_alloc(Allocator const &a, Ts&&... ts)#: Creates a pre-initialized future object with allocator (extension)

template<typename T, typename ...Ts> std::enable_if_t<std::is_constructible_v<T, Ts&&...> || std::is_void_v<T>, future<T>> make_ready_future(Ts&&... ts)#: The function creates a shared state that is immediately ready and returns a future associated with that shared state. For the returned future, valid() == true and is_ready() == true.

template<int DeductionGuard = 0, typename Allocator, typename T> future<hpx::util::decay_unwrap_t<T>> make_ready_future_alloc(Allocator const &a, T &&init)#

template<int DeductionGuard = 0, typename T> future<hpx::util::decay_unwrap_t<T>> make_ready_future(T &&init)#: The function creates a shared state that is immediately ready and returns a future associated with that shared state. For the returned future, valid() == true and is_ready() == true.

template<typename T> future<T> make_exceptional_future(std::exception_ptr const &e)#: Creates a pre-initialized future object which holds the given error (extension)

template<typename T, typename E> future<T> make_exceptional_future(E e)#: Creates a pre-initialized future object which holds the given error (extension)

template<int DeductionGuard = 0, typename T> future<hpx::util::decay_unwrap_t<T>> make_ready_future_at(hpx::chrono::steady_time_point const &abs_time, T &&init)#: Creates a pre-initialized future object which gets ready at a given point in time (extension)

template<int DeductionGuard = 0, typename T> future<hpx::util::decay_unwrap_t<T>> make_ready_future_after(hpx::chrono::steady_duration const &rel_time, T &&init)#: Creates a pre-initialized future object which gets ready after a given point in time (extension)

template<typename Allocator> inline future<void> make_ready_future_alloc(Allocator const &a)#

future<void> make_ready_future()#: The function creates a shared state that is immediately ready and returns a future associated with that shared state. For the returned future, valid() == true and is_ready() == true.

inline future<void> make_ready_future_at(hpx::chrono::steady_time_point const &abs_time)#: Creates a pre-initialized future object which gets ready at a given point in time (extension)

inline future<void> make_ready_future_after(hpx::chrono::steady_duration const &rel_time)#: Creates a pre-initialized future object which gets ready after a given point in time (extension)

template<typename R> class future : public hpx::lcos::detail::future_base<future<R>, R>#

#include <future_fwd.hpp>

The class template hpx::future provides a mechanism to access the result of asynchronous operations:

An asynchronous operation (created via hpx::async, hpx::packaged_task, or hpx::promise) can provide a hpx::future object to the creator of that asynchronous operation.
The creator of the asynchronous operation can then use a variety of methods to query, wait for, or extract a value from the hpx::future. These methods may block if the asynchronous operation has not yet provided a value.
When the asynchronous operation is ready to send a result to the creator, it can do so by modifying shared state (e.g. hpx::promise::set_value) that is linked to the creator’s hpx::future. Note that hpx::future references shared state that is not shared with any other asynchronous return objects (as opposed to hpx::shared_future).

Public Types

using result_type = R #

using shared_state_type = typename base_type::shared_state_type#

Public Functions

constexpr future() noexcept = default#

future(future &&other) noexcept = default#

inline future(future<future> &&other) noexcept#

inline future(future<shared_future<R>> &&other) noexcept#

template<typename T> inline future(future<T> &&other, std::enable_if_t<std::is_void_v<R> && !traits::is_future_v<T>, T>* = nullptr) noexcept#

~future() = default#

future &operator=(future &&other) noexcept = default#

inline shared_future<R> share() noexcept#

inline hpx::traits::future_traits<future>::result_type get()#

inline hpx::traits::future_traits<future>::result_type get(error_code &ec)#

template<typename F> inline decltype(auto) then(F &&f, error_code &ec = throws)#

Attaches a continuation to *this. The behavior is undefined if *this has no associated shared state (i.e., valid()==false ).

In cases where decltype(func(*this)) is future<R>, the resulting type is future<R> instead of future<future<R>>. Effects:

The continuation is called when the object’s shared state is ready (has a value or exception stored).
The continuation launches according to the specified launch policy or executor.
When the executor or launch policy is not provided the continuation inherits the parent’s launch policy or executor.
If the parent was created with std::promise or with a packaged_task (has no associated launch policy), the continuation behaves the same as the third overload with a policy argument of launch::async | launch::deferred and the same argument for func.
If the parent has a policy of launch::deferred and the continuation does not have a specified launch policy or scheduler, then the parent is filled by immediately calling .wait(), and the policy of the antecedent is launch::deferred

Note

Postcondition:

The future object is moved to the parameter of the continuation function.
valid() == false on original future object immediately after it returns.

Template Parameters

F – The type of the function/function object to use (deduced). F must meet requirements of MoveConstructible.
error_code – The type of error code.

Parameters

f – A continuation to be attached.
ec – Used to hold error code value originated during the operation. Defaults to throws — A special ‘throw on error’ error_code.

Returns

An object of type future<decltype(func(*this))> that refers to the shared state created by the continuation.

template<typename T0, typename F> inline decltype(auto) then(T0 &&t0, F &&f, error_code &ec = throws)#

Attaches a continuation to *this. The behavior is undefined if *this has no associated shared state (i.e., valid()==false ). \copydetail hpx::future::then(F&& f, error_code& ec = throws)

Note

Postcondition:

The future object is moved to the parameter of the continuation function.
valid() == false on original future object immediately after it returns.

Template Parameters

T0 – The type of executor or launch policy.
F – The type of the function/function object to use (deduced). F must meet requirements of MoveConstructible.
error_code – The type of error code.

Parameters

t0 – The executor or launch policy to be used.
f – A continuation to be attached.
ec – Used to hold error code value originated during the operation. Defaults to throws — A special ‘throw on error’ error_code.

Returns

An object of type future<decltype(func(*this))> that refers to the shared state created by the continuation.

template<typename Allocator, typename F> inline auto then_alloc(Allocator const &alloc, F &&f, error_code &ec = throws) -> decltype(base_type::then_alloc(alloc, HPX_MOVE(*this), HPX_FORWARD(F, f), ec))#

Private Types

using base_type = lcos::detail::future_base<future<R>, R>#

Private Functions

inline explicit future(hpx::intrusive_ptr<shared_state_type> const &state)#

inline explicit future(hpx::intrusive_ptr<shared_state_type> &&state)#

template<typename SharedState> inline explicit future(hpx::intrusive_ptr<SharedState> const &state)#

Friends

friend struct hpx::traits::future_access

struct invalidate#

Public Functions

inline explicit constexpr invalidate(future &f) noexcept#

inline ~invalidate()#

Public Members

future &f_#

template<typename R> class shared_future : public hpx::lcos::detail::future_base<shared_future<R>, R>#

#include <future_fwd.hpp>

The class template hpx::shared_future provides a mechanism to access the result of asynchronous operations, similar to hpx::future, except that multiple threads are allowed to wait for the same shared state. Unlike hpx::future, which is only moveable (so only one instance can refer to any particular asynchronous result), hpx::shared_future is copyable and multiple shared future objects may refer to the same shared state. Access to the same shared state from multiple threads is safe if each thread does it through its own copy of a shared_future object.

Public Types

using result_type = R #

using shared_state_type = typename base_type::shared_state_type#

Public Functions

constexpr shared_future() noexcept = default#

shared_future(shared_future const &other) = default#

shared_future(shared_future &&other) noexcept = default#

inline shared_future(future<R> &&other) noexcept#

inline shared_future(future<shared_future> &&other) noexcept#

template<typename T> inline shared_future(shared_future<T> const &other, std::enable_if_t<std::is_void_v<R> && !traits::is_future_v<T>, T>* = nullptr)#

~shared_future() = default#

shared_future &operator=(shared_future const &other) = default#

shared_future &operator=(shared_future &&other) noexcept = default#

inline hpx::traits::future_traits<shared_future>::result_type get() const#

inline hpx::traits::future_traits<shared_future>::result_type get(error_code &ec) const#

template<typename F> inline decltype(auto) then(F &&f, error_code &ec = throws) const#

Attaches a continuation to *this. The behavior is undefined if *this has no associated shared state (i.e., valid()==false ).

In cases where decltype(func(*this)) is future<R>, the resulting type is future<R> instead of future<future<R>>. Effects:

The continuation is called when the object’s shared state is ready (has a value or exception stored).
The continuation launches according to the specified launch policy or executor.
When the executor or launch policy is not provided the continuation inherits the parent’s launch policy or executor.
If the parent was created with std::promise or with a packaged_task (has no associated launch policy), the continuation behaves the same as the third overload with a policy argument of launch::async | launch::deferred and the same argument for func.
If the parent has a policy of launch::deferred and the continuation does not have a specified launch policy or scheduler, then the parent is filled by immediately calling .wait(), and the policy of the antecedent is launch::deferred

Note

Postcondition:

The future object is moved to the parameter of the continuation function.
valid() == false on original future object immediately after it returns.

Template Parameters

F – The type of the function/function object to use (deduced). F must meet requirements of MoveConstructible.
error_code – The type of error code.

Parameters

f – A continuation to be attached.
ec – Used to hold error code value originated during the operation. Defaults to throws — A special ‘throw on error’ error_code.

Returns

An object of type future<decltype(func(*this))> that refers to the shared state created by the continuation.

template<typename T0, typename F> inline decltype(auto) then(T0 &&t0, F &&f, error_code &ec = throws) const#

Attaches a continuation to *this. The behavior is undefined if *this has no associated shared state (i.e., valid()==false ). \copydetail hpx::future::then(F&& f, error_code& ec = throws)

Note

Postcondition:

The future object is moved to the parameter of the continuation function.
valid() == false on original future object immediately after it returns.

Template Parameters

T0 – The type of executor or launch policy.
F – The type of the function/function object to use (deduced). F must meet requirements of MoveConstructible.
error_code – The type of error code.

Parameters

t0 – The executor or launch policy to be used.
f – A continuation to be attached.
ec – Used to hold error code value originated during the operation. Defaults to throws — A special ‘throw on error’ error_code.

Returns

An object of type future<decltype(func(*this))> that refers to the shared state created by the continuation.

template<typename Allocator, typename F> inline auto then_alloc(Allocator const &alloc, F &&f, error_code &ec = throws) -> decltype(base_type::then_alloc(alloc, HPX_MOVE(*this), HPX_FORWARD(F, f), ec))#

Private Types

using base_type = lcos::detail::future_base<shared_future<R>, R>#

Private Functions

inline explicit shared_future(hpx::intrusive_ptr<shared_state_type> const &state)#

inline explicit shared_future(hpx::intrusive_ptr<shared_state_type> &&state)#

template<typename SharedState> inline explicit shared_future(hpx::intrusive_ptr<SharedState> const &state)#

Friends

friend struct hpx::traits::future_access

namespace lcos#

Functions

template<typename R, typename U> HPX_DEPRECATED_V (1, 8, "hpx::lcos::make_future is deprecated. Use hpx::make_future instead.") hpx

template<typename R, typename U, typename Conv> HPX_DEPRECATED_V (1, 8, "hpx::lcos::make_future is deprecated. Use hpx::make_future instead.") hpx

template<typename T, typename Allocator, typename... Ts> HPX_DEPRECATED_V (1, 8, "hpx::lcos::make_ready_future_alloc is deprecated. Use " "hpx::make_ready_future_alloc instead.") std

template<typename T, typename... Ts> HPX_DEPRECATED_V (1, 8, "hpx::lcos::make_ready_future is deprecated. Use " "hpx::make_ready_future instead.") std

template<typename T> HPX_DEPRECATED_V (1, 8, "hpx::lcos::make_exceptional_future is deprecated. Use " "hpx::make_exceptional_future instead.") hpx

template<typename T, typename E> HPX_DEPRECATED_V (1, 8, "hpx::lcos::make_exceptional_future is deprecated. Use " "hpx::make_exceptional_future instead.") hpx

template<int DeductionGuard = 0, typename T> HPX_DEPRECATED_V (1, 8, "hpx::lcos::make_ready_future_at is deprecated. Use " "hpx::make_ready_future_at instead.") hpx

template<int DeductionGuard = 0, typename T> HPX_DEPRECATED_V (1, 8, "hpx::lcos::make_ready_future_after is deprecated. Use " "hpx::make_ready_future_after instead.") hpx

template<typename Allocator> HPX_DEPRECATED_V (1, 8, "hpx::lcos::make_ready_future_alloc is deprecated. Use " "hpx::make_ready_future_alloc instead.") hpx

template<typename T> HPX_DEPRECATED_V (1, 8, "hpx::lcos::make_ready_future is deprecated. Use " "hpx::make_ready_future instead.") std

template<typename T> HPX_DEPRECATED_V (1, 8, "hpx::lcos::make_ready_future_at is deprecated. Use " "hpx::make_ready_future_at instead.") std

template<typename T> HPX_DEPRECATED_V (1, 8, "hpx::lcos::make_ready_future_after is deprecated. Use " "hpx::make_ready_future_after instead.") std

namespace serialization

Functions

template<typename Archive, typename T> void serialize(Archive &ar, ::hpx::future<T> &f, unsigned version)#

template<typename Archive, typename T> void serialize(Archive &ar, ::hpx::shared_future<T> &f, unsigned version)#

HPX master documentation

hpx/futures/future.hpp

hpx/futures/future.hpp#