futures::promise

Futures / Shared State / promise

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

template <
    class R, 
    class Options = future_options<executor_opt<default_executor_type>, continuable_opt>> 
class promise;

A shared state that will later be acquired by a future type.

Template Parameters

R - The shared state type

Description

The shared state is accessed by a future and a promise. The promise can write to the shared state while the future can read from it.

The shared state is an implementation detail that takes advantages of the properties of futures and promises to avoid locking and wasteful memory allocations.

Inherits from promise_base< R, future_options< executor_opt< default_executor_type >, continuable_opt > >

Public Functions

Member Functions	Description
set_value	Set the promise value. ^{(function template)}
swap	Swap the value of two promises. ^(function)
get_future	Gets a future that shares its state with this promise. ^(function)
set_exception	Set the promise result as an exception. ^(function)

Protected Functions

Member Protected Functions	Description
swap	^(function)
get_shared_state	^(function)

Additional inherited members

Public Functions^{(inherited from futures::promise_base< R, future_options< executor_opt< default_executor_type >, continuable_opt > >)}

Member Functions	Description
promise_base	Create the base promise with std::allocator. ^(function)
operator=	No copy assignment. ^(function)
~promise_base	Destructor. ^{(virtual function)}

Public Functions

function set_value

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

template <class... Args>
void
set_value(Args &&... args);

Set the promise value.

Parameters

args - arguments to set the promise

Description

After this value is set, it can be obtained by the future object

Exception Safety

Basic exception guarantee.

function swap

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

void
swap(promise & other) noexcept;

Swap the value of two promises.

Exception Safety

Throws nothing.

function get_future

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

basic_future< R, Options >
get_future();

Gets a future that shares its state with this promise.

Description

This function constructs a future object that shares its state with this promise. Because this library handles more than a single future type, the future type we want is a template parameter.

This function expects future type constructors to accept pointers to shared states.

Exception Safety

Basic exception guarantee.

function set_exception

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

(1)

void
set_exception(std::exception_ptr p);

(2)

template <class E>
requires std::is_base_of_v<std::exception, E>
void
set_exception(E e);

Set the promise result as an exception.

Notes

The set_value operation is only available at the concrete derived class, where we know the class type

Exception Safety

Basic exception guarantee.

Protected Functions

function swap

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

void
swap(promise_base & other) noexcept;

Exception Safety

Throws nothing.

function get_shared_state

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

constexpr
/* see return type below */
get_shared_state();

Exception Safety

Basic exception guarantee.

_{Updated on 2023-01-04}