hpx/futures/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)

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

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

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

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)