33 Concurrency support library [thread]

33.10 Futures [futures]

33.10.6 Class template promise [futures.promise]

namespace std { template<class R> class promise { public: promise(); template<class Allocator> promise(allocator_arg_t, const Allocator& a); promise(promise&& rhs) noexcept; promise(const promise&) = delete; ~promise(); // assignment promise& operator=(promise&& rhs) noexcept; promise& operator=(const promise&) = delete; void swap(promise& other) noexcept; // retrieving the result future<R> get_future(); // setting the result void set_value(see below); void set_exception(exception_ptr p); // setting the result with deferred notification void set_value_at_thread_exit(see below); void set_exception_at_thread_exit(exception_ptr p); }; template<class R, class Alloc> struct uses_allocator<promise<R>, Alloc>; }

For the primary template, R shall be an object type that meets the Cpp17Destructible requirements.

The implementation provides the template promise and two specializations, promise<R&> and promise<void>.

These differ only in the argument type of the member functions set_value and set_value_at_thread_exit, as set out in their descriptions, below.

The set_value, set_exception, set_value_at_thread_exit, and set_exception_at_thread_exit member functions behave as though they acquire a single mutex associated with the promise object while updating the promise object.

🔗

template<class R, class Alloc>
  struct uses_allocator<promise<R>, Alloc>
    : true_type { };

Preconditions: Alloc meets the Cpp17Allocator requirements ([allocator.requirements.general]).

🔗

promise();
template<class Allocator>
  promise(allocator_arg_t, const Allocator& a);

Effects: Creates a shared state.

The second constructor uses the allocator a to allocate memory for the shared state.

🔗

promise(promise&& rhs) noexcept;

Effects: Transfers ownership of the shared state of rhs (if any) to the newly-constructed object.

Postconditions: rhs has no shared state.

🔗

~promise();

Effects: Abandons any shared state ([futures.state]).

🔗

promise& operator=(promise&& rhs) noexcept;

Effects: Abandons any shared state ([futures.state]) and then as if promise(std::move(rhs)).swap(*this).

Returns: *this.

🔗

void swap(promise& other) noexcept;

Effects: Exchanges the shared state of *this and other.

Postconditions: *this has the shared state (if any) that other had prior to the call to swap.

other has the shared state (if any) that *this had prior to the call to swap.

🔗

future<R> get_future();

Synchronization: Calls to this function do not introduce data races ([intro.multithread]) with calls to set_value, set_exception, set_value_at_thread_exit, or set_exception_at_thread_exit.

[Note 1:

Such calls need not synchronize with each other.

— end note]

Returns: A future<R> object with the same shared state as *this.

Throws: future_error if *this has no shared state or if get_future has already been called on a promise with the same shared state as *this.

Error conditions:

(16.1)
future_already_retrieved if get_future has already been called on a promise with the same shared state as *this.
(16.2)
no_state if *this has no shared state.

🔗

void promise::set_value(const R& r);
void promise::set_value(R&& r);
void promise<R&>::set_value(R& r);
void promise<void>::set_value();

Effects: Atomically stores the value r in the shared state and makes that state ready ([futures.state]).

Throws:

(18.1)
future_error if its shared state already has a stored value or exception, or
(18.2)
for the first version, any exception thrown by the constructor selected to copy an object of R, or
(18.3)
for the second version, any exception thrown by the constructor selected to move an object of R.

Error conditions:

(19.1)
promise_already_satisfied if its shared state already has a stored value or exception.
(19.2)
no_state if *this has no shared state.

🔗

void set_exception(exception_ptr p);

Preconditions: p is not null.

Effects: Atomically stores the exception pointer p in the shared state and makes that state ready ([futures.state]).

Throws: future_error if its shared state already has a stored value or exception.

Error conditions:

(23.1)
promise_already_satisfied if its shared state already has a stored value or exception.
(23.2)
no_state if *this has no shared state.

🔗

void promise::set_value_at_thread_exit(const R& r);
void promise::set_value_at_thread_exit(R&& r);
void promise<R&>::set_value_at_thread_exit(R& r);
void promise<void>::set_value_at_thread_exit();

Effects: Stores the value r in the shared state without making that state ready immediately.

Schedules that state to be made ready when the current thread exits, after all objects of thread storage duration associated with the current thread have been destroyed.

Throws:

(25.1)
future_error if its shared state already has a stored value or exception, or
(25.2)
for the first version, any exception thrown by the constructor selected to copy an object of R, or
(25.3)
for the second version, any exception thrown by the constructor selected to move an object of R.

Error conditions:

(26.1)
promise_already_satisfied if its shared state already has a stored value or exception.
(26.2)
no_state if *this has no shared state.

🔗

void set_exception_at_thread_exit(exception_ptr p);

Preconditions: p is not null.

Effects: Stores the exception pointer p in the shared state without making that state ready immediately.

Schedules that state to be made ready when the current thread exits, after all objects of thread storage duration associated with the current thread have been destroyed.

Throws: future_error if an error condition occurs.

Error conditions:

(30.1)
promise_already_satisfied if its shared state already has a stored value or exception.
(30.2)
no_state if *this has no shared state.

🔗

template<class R>
  void swap(promise<R>& x, promise<R>& y) noexcept;

Effects: As if by x.swap(y).