Futures Library: Waiting

Basic function to wait for futures.

This module defines a variety of auxiliary functions to wait for futures.

Functions

Member Functions	Description
await	Wait for future types and retrieve their values. ^{(function template)}
wait_for_all	Wait for a sequence of futures to be ready. ^{(function template)}
wait_for_all_for	Wait for a sequence of futures to be ready. ^{(function template)}
wait_for_all_until	Wait for a sequence of futures to be ready. ^{(function template)}
wait_for_any	Wait for any future in a sequence to be ready. ^{(function template)}
wait_for_any_for	Wait for any future in a sequence to be ready. ^{(function template)}
wait_for_any_until	Wait for any future in a sequence to be ready. ^{(function template)}

Functions

function await

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

(1)

template <future_like Future>
/* see return type below */
await(Future && f);

(2)

template <future_like... Futures>
/* see return type below */
await(Futures &&... fs);

Wait for future types and retrieve their values.
Wait for future types and retrieve their values as a tuple.

Parameters

f - A future object
fs - Future objects

Return value

The result of the future object

Description

This syntax is most useful for cases where we are immediately requesting the future result.

The function also makes the syntax optionally a little closer to languages such as javascript.

Notes

This function only participates in overload resolution if all types are futures.

Exception Safety

Basic exception guarantee.

function wait_for_all

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

(1)

template <std::input_iterator Iterator>
requires future_like<std::iter_value_t<Iterator>>
void
wait_for_all(Iterator first, Iterator last);

(2)

template <std::ranges::range Range>
requires future_like<std::ranges::range_value_t<Range>>
void
wait_for_all(Range && r);

(3)

template <future_like... Fs>
void
wait_for_all(Fs &&... fs);

(4)

template <class Tuple>
requires /* see requirements below */
void
wait_for_all(Tuple && t);

Wait for a sequence of futures to be ready.

Template Parameters

Fs - A list of future types
Iterator - Iterator type in a range of futures
Range - A range of futures type

Parameters

first - Iterator to the first element in the range
fs - A list of future objects
last - Iterator to one past the last element in the range
r - Range of futures

Description

(1) This function waits for all futures in the range [first, last) to be ready. It simply waits iteratively for each of the futures to be ready.

(2) This function waits for all futures in the range r to be ready. It simply waits iteratively for each of the futures to be ready.

(3) This function waits for all specified futures fs... to be ready.

It creates a compile-time fixed-size data structure to store references to all of the futures and then waits for each of the futures to be ready.

Notes

This function is adapted from boost::wait_for_all

Exception Safety

Basic exception guarantee.

See Also

boost.thread wait_for_all

function wait_for_all_for

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

(1)

template <class Iterator, class Rep, class Period>
requires is_future_like_v<iter_value_t<Iterator>>
future_status
wait_for_all_for(
    std::chrono::duration< Rep, Period > const & timeout_duration, 
    Iterator first, 
    Iterator last);

(2)

template <class Range, class Rep, class Period>
requires is_range_v<Range> && is_future_like_v<range_value_t<Range>>
future_status
wait_for_all_for(
    std::chrono::duration< Rep, Period > const & timeout_duration, 
    Range && r);

(3)

template <future_like... Fs, class Rep, class Period>
future_status
wait_for_all_for(
    std::chrono::duration< Rep, Period > const & timeout_duration, 
    Fs &&... fs);

(4)

template <class Tuple, class Rep, class Period>
requires /* see requirements below */
future_status
wait_for_all_for(
    std::chrono::duration< Rep, Period > const & timeout_duration, 
    Tuple && t);

Wait for a sequence of futures to be ready.

Template Parameters

Fs - Range of futures
Iterator - Iterator type in a range of futures
Period - Duration Period
Range - Range of futures
Rep - Duration Rep
Tuple - Tuple of futures

Parameters

first - Iterator to the first element in the range
fs - Future objects
last - Iterator to one past the last element in the range
r - Range of futures
t - Tuple of futures
timeout_duration - Time to wait for

Return value

future_status::ready if all futures got ready. future_status::timeout otherwise.

Exception Safety

Basic exception guarantee.

function wait_for_all_until

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

(1)

template <std::input_iterator Iterator, class Clock, class Duration>
requires future_like<std::iter_value_t<Iterator>>
future_status
wait_for_all_until(
    std::chrono::time_point< Clock, Duration > const & timeout_time, 
    Iterator first, 
    Iterator last);

(2)

template <std::ranges::range Range, class Clock, class Duration>
requires future_like<range_value_t<Range>>
future_status
wait_for_all_until(
    std::chrono::time_point< Clock, Duration > const & timeout_time, 
    Range && r);

(3)

template <future_like... Fs, class Clock, class Duration>
future_status
wait_for_all_until(
    std::chrono::time_point< Clock, Duration > const & timeout_time, 
    Fs &&... fs);

(4)

template <class Tuple, class Clock, class Duration>
requires /* see requirements below */
future_status
wait_for_all_until(
    std::chrono::time_point< Clock, Duration > const & timeout_time, 
    Tuple && t);

Wait for a sequence of futures to be ready.

Template Parameters

Clock - Time point clock
Duration - Time point duration
Fs - Future objects
Iterator - Iterator type in a range of futures
Range - Range of futures
Tuple - Tuple of futures

Parameters

first - Iterator to the first element in the range
fs - Future objects
last - Iterator to one past the last element in the range
r - Range of futures
t - Tuple of futures
timeout_time - Limit time point

Return value

future_status::ready if all futures got ready. future_status::timeout otherwise.

Exception Safety

Basic exception guarantee.

function wait_for_any

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

(1)

template <std::input_iterator Iterator>
requires future_like<iter_value_t<Iterator>>
Iterator
wait_for_any(Iterator first, Iterator last);

(2)

template <std::ranges::range Range>
requires future_like<range_value_t<Range>>
iterator_t< Range >
wait_for_any(Range && r);

(3)

template <future_like... Fs>
std::size_t
wait_for_any(Fs &&... fs);

(4)

template <class Tuple>
requires /* see requirements below */
std::size_t
wait_for_any(Tuple && t);

Wait for any future in a sequence to be ready.
Wait for any future in a sequence to be ready.
Wait for any future in a sequence to be ready.
Wait for any future in a tuple to be ready.

Template Parameters

Fs - A list of future types
Iterator - Iterator type in a range of futures

Parameters

first - Iterator to the first element in the range
fs - A list of future objects
last - Iterator to one past the last element in the range
r - Range of futures
t - A list of future objects

Return value

(1) Index of the first future that got ready
(2) Iterator to the first future that got ready

Description

(1) This function waits for any future in the range [first, last) to be ready.

Unlike wait_for_all, this function requires special data structures to allow that to happen without blocking.

For disjunctions, we have few options:

If the input futures support external notifiers:
- Attach continuations to notify when a task is over
If the input futures do not have lazy continuations:
- Polling in a busy loop until one of the futures is ready
- Polling with exponential backoffs until one of the futures is ready
- Launching n continuation tasks that set a promise when one of the futures is ready
- Hybrids, usually polling for short tasks and launching threads for other tasks
If the input futures are mixed in regards to lazy continuations:
- Mix the strategies above, depending on each input future

If the thresholds for these strategies are reasonable, this should be efficient for futures with or without lazy continuations.

(2) This function waits for any future in the range r to be ready. This function requires special data structures to allow that to happen without blocking.

(3) This function waits for all specified futures fs... to be ready.

(4) This function waits for all specified futures fs... to be ready.

Notes

This function is adapted from boost::wait_for_any

Exception Safety

Basic exception guarantee.

See Also

boost.thread wait_for_any

function wait_for_any_for

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

(1)

template <std::input_iterator Iterator, class Rep, class Period>
requires future_like<iter_value_t<Iterator>>
Iterator
wait_for_any_for(
    std::chrono::duration< Rep, Period > const & timeout_duration, 
    Iterator first, 
    Iterator last);

(2)

template <std::ranges::range Range, class Rep, class Period>
requires future_like<std::ranges::range_value_t<Range>>
iterator_t< Range >
wait_for_any_for(
    std::chrono::duration< Rep, Period > const & timeout_duration, 
    Range && r);

(3)

template <future_like... Fs, class Rep, class Period>
std::size_t
wait_for_any_for(
    std::chrono::duration< Rep, Period > const & timeout_duration, 
    Fs &&... fs);

(4)

template <class Tuple, class Rep, class Period>
requires /* see requirements below */
std::size_t
wait_for_any_for(
    std::chrono::duration< Rep, Period > const & timeout_duration, 
    Tuple && t);

Wait for any future in a sequence to be ready.

Template Parameters

Fs - Future types
Iterator - Iterator type in a range of futures
Period - Duration Period
Range - Iterator type in a range of futures
Rep - Duration Rep
Tuple - Tuple of futures

Parameters

first - Iterator to the first element in the range
fs - Future objects
last - Iterator to one past the last element in the range
r - Range of futures
t - tuple of futures
timeout_duration - Time to wait for

Return value

(1) Index of the future which got ready
(2) Iterator to the future which got ready

Exception Safety

Basic exception guarantee.

function wait_for_any_until

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

(1)

template <std::input_iterator Iterator, class Clock, class Duration>
requires future_like<iter_value_t<Iterator>>
Iterator
wait_for_any_until(
    std::chrono::time_point< Clock, Duration > const & timeout_time, 
    Iterator first, 
    Iterator last);

(2)

template <std::ranges::range Range, class Clock, class Duration>
requires future_like<range_value_t<Range>>
iterator_t< Range >
wait_for_any_until(
    std::chrono::time_point< Clock, Duration > const & timeout_time, 
    Range && r);

(3)

template <future_like... Fs, class Clock, class Duration>
std::size_t
wait_for_any_until(
    std::chrono::time_point< Clock, Duration > const & timeout_time, 
    Fs &&... fs);

(4)

template <class Tuple, class Clock, class Duration>
requires /* see requirements below */
std::size_t
wait_for_any_until(
    std::chrono::time_point< Clock, Duration > const & timeout_time, 
    Tuple && t);

Wait for any future in a sequence to be ready.

Template Parameters

Clock - Time point clock
Duration - Time point duration
Fs - Future types
Iterator - Iterator type in a range of futures
Range - Range of futures
Tuple - Tuple of future types

Parameters

first - Iterator to the first element in the range
fs - Future objects
last - Iterator to one past the last element in the range
r - Range of futures
t - Tuple of future objects
timeout_time - Limit time point

Return value

(1) Index of the future which got ready
(2) Iterator to the future which got ready

Exception Safety

Basic exception guarantee.

_{Updated on 2023-01-04}