futures::when_any_future

Adaptors / when_any_future

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

template <class Sequence> 
class when_any_future;

Future object referring to the result of a disjunction of futures.

Description

This class implements another future type to identify when one of a list of tasks is over.

As with when_all, this class acts as a future that checks the results of other futures to avoid creating a real disjunction of futures that would need another thread for polling.

Not-polling is easier to emulate for future conjunctions (when_all) because we can sleep on each task until they are all done, since we need all of them anyway.

Public Functions

Member Functions	Description
(constructor)	Default constructor. (function)
(destructor) = default	Releases any shared state. (function)
operator=	Assigns the contents of another future object. (function)
get	Wait until any future has a valid result and retrieves it. (function)
valid const	Checks if the future refers to a shared state. (function)
wait	Blocks until the result becomes available. (function)
wait_for	Waits for the result to become available. (function template)
wait_until	Waits for a result to become available. (function template)
is_ready const	Check if it's ready. (function)
release	Move the underlying sequence somewhere else. (function)
lazy_continuable_size const	Get number of internal futures with lazy continuations. (function)
all_lazy_continuable const	Check if all internal types are lazy continuable. (function)
compile_time_size	Get size, if we know that at compile time. (function)

Public Functions

function when_any_future

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

(1)

when_any_future() = default;

(2)

explicit when_any_future(
    sequence_type && v);

(3)

when_any_future(
    when_any_future && other);

(4)

when_any_future(when_any_future const & other) = delete;

1. Default constructor.
2. Move a sequence of futures into the when_any_future constructor.
3. Move constructor.
4. when_any_future is not CopyConstructible

Description

(1) Constructs a when_any_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.

We immediately set up the notifiers for any input future that supports lazy continuations.

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

This is a class that controls resources, and their behavior needs to be moved. However, unlike a vector, some notifier resources cannot be moved and might need to be recreated, because they expect the underlying futures to be in a given address to work.

We cannot move the notifiers because these expect things to be notified at certain addresses. This means the notifiers in other have to be stopped and we have to be sure of that before its destructor gets called.

There are two in operations here.

• Asking the notifiers to stop and waiting
  • This is what we need to do at the destructor because we can't destruct "this" until we are sure no notifiers are going to try to notify this object
• Asking the notifiers to stop
  • This is what we need to do when moving, because we know we won't need these notifiers anymore. When the moved object gets destructed, it will ensure its notifiers are stopped and finish the task.

Exception Safety

Basic exception guarantee.

function ~when_any_future

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

~when_any_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, but we have to stop notifiers if we have any, because these notifiers might later try to set tokens in a future that no longer exists.

Exception Safety

Basic exception guarantee.

function operator=

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

(1)

when_any_future &
operator=(
    when_any_future && other);

(2)

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

1. Assigns the contents of another future object.
2. Copy assigns the contents of another when_any_future object.

Description

(1) 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.

(2) when_any_future is not copy assignable.

Exception Safety

Basic exception guarantee.

function get

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

when_any_result< sequence_type >
get();

Wait until any future has a valid result and retrieves it.

Return value

A when_any_result holding the future objects

Description

It effectively calls wait() in order to wait for the result. This avoids replicating the logic behind continuations, polling, and notifiers.

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_any.hpp>}

bool
valid() const noexcept;

Checks if the future refers to a shared state.

Return value

Return true if underlying futures are valid

Description

This future is always valid() unless there are tasks and they are all invalid

Exception Safety

Throws nothing.

See Also

• std::experimental::when_any

function wait

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

void
wait();

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_any.hpp>}

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

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. Not-polling is easier to emulate for future conjunctions (when_all) because we can sleep on each task until they are all done, since we need all of them anyway.

Exception Safety

Basic exception guarantee.

See Also

• https://en.m.wikipedia.org/wiki/Exponential_backoff

function wait_until

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

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

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 is_ready

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

(1)

bool
is_ready() const;

(2)

bool
is_ready(size_t index) const;

1. Check if it's ready.
2. Check if the i-th future is ready.

Exception Safety

Basic exception guarantee.

function release

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

sequence_type &&
release();

Move the underlying sequence somewhere else.

Description

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

Exception Safety

Basic exception guarantee.

function lazy_continuable_size

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

constexpr size_t
lazy_continuable_size() const;

Get number of internal futures with lazy continuations.

Exception Safety

Basic exception guarantee.

function all_lazy_continuable

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

constexpr bool
all_lazy_continuable() const;

Check if all internal types are lazy continuable.

Exception Safety

Basic exception guarantee.

function compile_time_size

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

static constexpr size_t
compile_time_size();

Get size, if we know that at compile time.

Exception Safety

Basic exception guarantee.

---

_{Updated on 2023-01-04}