futures::basic_future

Futures / Future types / basic_future

^{Defined in header <futures/future.hpp>}

template <class R, class Options = future_options<>> 
class basic_future;

A basic future type with custom features.

Template Parameters

R - Type of element
Options - Future value options

Description

Note that these classes only provide the capabilities of tracking these features, such as continuations.

Setting up these capabilities (creating tokens or setting main future to run continuations) needs to be done when the future is created in a function such as async by creating the appropriate state for each feature.

All this behavior is already encapsulated in the async function.

Public Types

Member Types	Definition
value_type	`R` ^(using)

Public Functions

Getting the result	Description
get	Returns the result. ^(function)
get_exception_ptr	Get exception pointer without throwing an exception. ^(function)

Continuations	Description
then	Attaches a continuation to a future. ^{(function template)}
get_executor const	Get the current executor for this task. ^(function)

Constructors	Description
(destructor)	Destructor. ^(function)
(constructor)	Constructor. ^(function)
operator=	Copy assignment. ^(function)

Sharing	Description
share	Create another future whose state is shared. ^(function)

Future state	Description
valid const	Checks if the future refers to a valid operation state. ^(function)
wait	Waits for the result to become available. ^(function)
wait_for	Waits for the result, returns if it is unavailable for duration. ^{(function template)}
wait_until	Waits for the result, returns if it is unavailable for duration. ^{(function template)}
is_ready const	Checks if the associated operation state is ready. ^(function)
detach	Tell this future not to join at destruction. ^(function)

Stop requests	Description
request_stop	Requests execution stop via the shared stop state of the task. ^(function)
get_stop_source const	Get this future's stop source. ^(function)
get_stop_token const	Get this future's stop token. ^(function)

Public Types

using value_type

^{Defined in header <futures/future.hpp>}

using value_type = R;

Public Functions

function get

^{Defined in header <futures/future.hpp>}

/* see return type below */
get();

Returns the result.

Description

The get member function waits until the future has a valid result and retrieves it.

It effectively calls wait() in order to wait for the result.

The behavior is undefined if valid() is false before the call to this function.

If the future is unique, any shared state is released and valid() is false after a call to this member function.

Unique futures:
- R -> return R
- R& -> return R&
- void -> return void
Shared futures:
- R -> return const R&
- R& -> return R&
- void -> return void

Exception Safety

Basic exception guarantee.

function get_exception_ptr

^{Defined in header <futures/future.hpp>}

std::exception_ptr
get_exception_ptr();

Get exception pointer without throwing an exception.

Return value

An exception pointer

Description

If the future does not hold an exception, the exception_ptr is nullptr.

This extends future objects so that we can always check if the future contains an exception without throwing it.

Exception Safety

Basic exception guarantee.

function then

^{Defined in header <futures/future.hpp>}

(1)

template <class Executor, class Fn>
/* see return type below */
then(Executor const & ex, Fn && fn);

(2)

template <class Fn>
/* see return type below */
then(Fn && fn);

Attaches a continuation to a future.
Attaches a continuation to a future on the same executor.

Template Parameters

Executor - Executor type
Fn - Function type

Parameters

ex - An executor
fn - A continuation function

Return value

The continuation future

Description

(1) Attach the continuation function to this future object. The behavior is undefined if this future has no associated operation state (i.e., valid() == false).

Creates an operation state associated with the future object to be returned.

When the shared state currently associated with this future is ready, the continuation is called on the specified executor.

Any value returned from the continuation is stored as the result in the operation state of the returned future object. Any exception propagated from the execution of the continuation is stored as the exceptional result in the operation state of the returned future object.

A continuation to an eager future is also eager. If this future is eager, the continuation is attached to a list of continuations of this future.

A continuation to a deferred future is also deferred. If this future is deferred, this future is stored as the parent future of the next future.

If this future is ready, the continuation is directly launched or scheduled in the specified executor.

(2) Attach the continuation function to this future object with the default executor.

When the shared state currently associated with this future is ready, the continuation is called on the same executor as this future. If no executor is associated with this future, the default executor is used.

Notes

(1) This function only participates in overload resolution if the future supports continuations
(2)
Unlike std::experimental::future, when the return type of the continuation function is also a future, this function performs no implicit unwrapping on the return type with the get function. This (i) simplifies the development of generic algorithms with futures, (ii) makes the executor for the unwrapping task explicit, and (iii) allows the user to retrieve the returned type as a future or as its unwrapped type.
This function only participates in overload resolution if the future supports continuations

Exception Safety

Basic exception guarantee.

function get_executor

^{Defined in header <futures/future.hpp>}

const Options::executor_t &
get_executor() const;

Get the current executor for this task.

Return value

The executor associated with this future instance

Notes

This function only participates in overload resolution if future_options has an associated executor

Exception Safety

Basic exception guarantee.

function ~basic_future

^{Defined in header <futures/future.hpp>}

~basic_future();

Destructor.

Exception Safety

Basic exception guarantee.

function basic_future

^{Defined in header <futures/future.hpp>}

(1)

basic_future() = default;

(2)

basic_future(basic_future const & other) = default;

(3)

basic_future(basic_future && other) noexcept;

Constructor.
Copy constructor.
Move constructor.

Description

(1) The default constructor creates an invalid future with no shared state.

After construction, valid() == false.

(2) Constructs a shared future that refers to the same shared state, if any, as other.

(3) Constructs a basic_future with the operation state of other using move semantics.

After construction, other.valid() == false.

Notes

The copy constructor only participates in overload resolution if basic_future is shared.

Exception Safety

(1) Basic exception guarantee.
(2) Basic exception guarantee.
(3) Throws nothing.

function operator=

^{Defined in header <futures/future.hpp>}

(1)

basic_future &
operator=(basic_future const & other) = default;

(2)

basic_future &
operator=(basic_future && other) noexcept;

Copy assignment.
Move assignment.

Description

(1) Constructs a shared future that refers to the same shared state, if any, as other.

(2) Constructs a basic_future with the operation state of other using move semantics.

After construction, other.valid() == false.

Notes

The copy assignment only participates in overload resolution if basic_future is shared.

Exception Safety

(1) Basic exception guarantee.
(2) Throws nothing.

^{Defined in header <futures/future.hpp>}

basic_future< R, detail::append_future_option_t< shared_opt, Options > >
share();

Create another future whose state is shared.

Return value

A shared variant of this future

Description

Create a shared variant of the current future object.

If the current type is not shared, the object becomes invalid.

If the current type is already shared, the new object is equivalent to a copy.

Exception Safety

Basic exception guarantee.

function valid

^{Defined in header <futures/future.hpp>}

bool
valid() const;

Checks if the future refers to a valid operation state.

Return value

true if *this refers to a valid operation state

Description

This is the case only for futures that were not default-constructed or moved from until the first time get() or share() is called. If the future is shared, its state is not invalidated when get() is called.

If any member function other than the destructor, the move-assignment operator, or valid is called on a future that does not refer a valid operation state, a future_error will be throw to indicate no_state.

It is valid to move (or copy, for shared futures) from a future object for which valid() is false.

Exception Safety

Basic exception guarantee.

function wait

^{Defined in header <futures/future.hpp>}

(1)

void
wait() const;

(2)

void
wait();

Waits for the result to become available.

Description

Blocks until the result becomes available.

valid() == true after the call.

A future_uninitialized exception is thrown if valid() == false before the call to this function.

Exception Safety

Basic exception guarantee.

function wait_for

^{Defined in header <futures/future.hpp>}

(1)

template <class Rep, class Period>
future_status
wait_for(
    std::chrono::duration< Rep, Period > const & timeout_duration) const;

(2)

template <class Rep, class Period>
future_status
wait_for(
    std::chrono::duration< Rep, Period > const & timeout_duration);

Waits for the result, returns if it is unavailable for duration.

Parameters

timeout_duration - maximum duration to block for

Return value

future status

Description

Waits for the result to become available. Blocks until specified timeout_duration has elapsed or the result becomes available, whichever comes first. The return value identifies the state of the result.

If the future is deferred, the operation state might be converted into a shared operation state. This ensures that (i) the result will be computed only when explicitly requested, and (ii) the address of the operation state will not change once the result is requested.

This function may block for longer than timeout_duration due to scheduling or resource contention delays.

The behavior is undefined if valid() is false before the call to this function.

Exception Safety

Basic exception guarantee.

function wait_until

^{Defined in header <futures/future.hpp>}

(1)

template <class Clock, class Duration>
future_status
wait_until(
    std::chrono::time_point< Clock, Duration > const & timeout_time) const;

(2)

template <class Clock, class Duration>
future_status
wait_until(
    std::chrono::time_point< Clock, Duration > const & timeout_time);

Waits for the result, returns if it is unavailable for duration.

Parameters

timeout_time - maximum time point to block until

Return value

future status

Description

Waits for a result to become available. It blocks until specified timeout_time has been reached or the result becomes available, whichever comes first. The return value indicates why wait_until returned.

If the future is deferred, the operation state might be converted into a shared operation state. This ensures that (i) the result will be computed only when explicitly requested, and (ii) the address of the operation state will not change once the result is requested.

This function may block until after timeout_time due to scheduling or resource contention delays.

The behavior is undefined if valid() is false before the call to this function.

Exception Safety

Basic exception guarantee.

function is_ready

^{Defined in header <futures/future.hpp>}

bool
is_ready() const;

Checks if the associated operation state is ready.

Return value

true if the associated shared state is ready

Description

Checks if the associated shared state is ready.

The behavior is undefined if valid() is false.

Exception Safety

Basic exception guarantee.

function detach

^{Defined in header <futures/future.hpp>}

void
detach();

Tell this future not to join at destruction.

Description

For safety, all futures wait at destruction by default.

This function separates the execution from the future object, allowing execution to continue independently.

Exception Safety

Basic exception guarantee.

function request_stop

^{Defined in header <futures/future.hpp>}

bool
request_stop() noexcept;

Requests execution stop via the shared stop state of the task.

Return value

true if this invocation made a stop request

Description

Issues a stop request to the internal stop-state, if it has not yet already had stop requested. The task associated to the future can use the stop token to identify it should stop running.

The determination is made atomically, and if stop was requested, the stop-state is atomically updated to avoid race conditions.

Notes

This function only participates in overload resolution if the future supports stop tokens

Exception Safety

Throws nothing.

function get_stop_source

^{Defined in header <futures/future.hpp>}

stop_source
get_stop_source() const noexcept;

Get this future's stop source.

Return value

The stop source

Description

Returns a stop_source associated with the same shared stop-state as held internally by the future task object.

Notes

This function only participates in overload resolution if the future supports stop tokens

Exception Safety

Throws nothing.

function get_stop_token

^{Defined in header <futures/future.hpp>}

stop_token
get_stop_token() const noexcept;

Get this future's stop token.

Return value

The stop token

Description

Returns a stop_token associated with the same shared stop-state held internally by the future task object.

Notes

This function only participates in overload resolution if the future supports stop tokens

Exception Safety

Throws nothing.

_{Updated on 2023-01-04}

futures::basic_future

Public Types

Public Functions

Public Types

using value_type

Public Functions

function get

function get_exception_ptr

function then

function get_executor

function ~basic_future

function basic_future

function operator=

function share

function valid

function wait

function wait_for

function wait_until

function is_ready

function detach

function request_stop

function get_stop_source

function get_stop_token