futures::when_all_future

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

template <class Sequence> 
class when_all_future;

Proxy future class referring to a conjunction of futures from when_all.

Description

This class implements the behavior of the when_all operation as another future type, which can handle heterogeneous future objects.

This future type logically checks the results of other futures in place to avoid creating a real conjunction of futures that would need to be polling (or be a lazy continuation) on another thread.

If the user does want to poll on another thread, then this can be converted into a cfuture as usual with async. If the other future holds the when_all_state as part of its state, then it can become another future.

Public Functions

Member Functions	Description
(constructor)	Constructor. ^(function)
(destructor) = default	Releases any shared state. ^(function)
operator=	Assigns the contents of another future object. ^(function)
get	Wait until all futures have a valid result and retrieves it. ^(function)
valid const	Checks if the future refers to a shared state. ^(function)
wait const	Blocks until the result becomes available. ^(function)
wait_for const	Waits for the result to become available. ^{(function template)}
wait_until const	Waits for a result to become available. ^{(function template)}
release	Allow move the underlying sequence somewhere else. ^(function)
request_stop	Request the stoppable futures to stop. ^(function)

Public Functions

function when_all_future

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

(1)

when_all_future() = default;

(2)

explicit when_all_future(
    sequence_type && v);

(3)

when_all_future(
    when_all_future && other);

(4)

when_all_future(when_all_future const & other) = delete;

Constructor.
Move a sequence of futures into the when_all_future.
Move constructor.
when_all_future is not CopyConstructible

Description

(1) Constructs a when_all_future with no shared state. After construction, valid() == false

(2) The sequence is moved into this future object and the objects from which the sequence was created get invalidated

(3) Constructs a when_all_future with the shared state of other using move semantics. After construction, other.valid() == false

Exception Safety

Basic exception guarantee.

function ~when_all_future

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

~when_all_future() = default;

Releases any shared state.

Description

If the return object or provider holds the last reference to its shared state, the shared state is destroyed
the return object or provider gives up its reference to its shared state This means we just need to let the internal futures destroy themselves

Exception Safety

Basic exception guarantee.

function operator=

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

(1)

when_all_future &
operator=(
    when_all_future && other);

(2)

when_all_future &
operator=(when_all_future const & other) = delete;

Assigns the contents of another future object.
when_all_future is not CopyAssignable.

Description

Releases any shared state and move-assigns the contents of other to *this. After the assignment, other.valid() == false and this->valid() will yield the same value as other.valid() before the assignment.

Exception Safety

Basic exception guarantee.

function get

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

sequence_type
get();

Wait until all futures have a valid result and retrieves it.

Description

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. Any shared state is released. valid() is false after a call to this method. The value v stored in the shared state, as std::move(v)

Exception Safety

Basic exception guarantee.

function valid

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

bool
valid() const noexcept;

Checks if the future refers to a shared state.

Exception Safety

Throws nothing.

function wait

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

void
wait() const;

Blocks until the result becomes available.

Description

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

Exception Safety

Basic exception guarantee.

function wait_for

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

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

Waits for the result to become available.

Parameters

timeout_duration - Time to wait

Return value

Status of the future after the specified duration

Description

Blocks until specified timeout_duration has elapsed or the result becomes available, whichever comes first.

Exception Safety

Basic exception guarantee.

function wait_until

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

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

Waits for a result to become available.

Parameters

timeout_time - The timepoint to wait until

Return value

Status of the future after the specified duration

Description

It blocks until specified timeout_time has been reached or the result becomes available, whichever comes first

Exception Safety

Basic exception guarantee.

function release

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

sequence_type &&
release();

Allow move the underlying sequence somewhere else.

Description

The when_all_future is left empty and should now be considered invalid. This is useful for the algorithm that merges two wait_all_future objects without forcing encapsulation of the merge function.

Exception Safety

Basic exception guarantee.

function request_stop

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

bool
request_stop() noexcept;

Request the stoppable futures to stop.

Exception Safety

Throws nothing.

_{Updated on 2023-01-04}