[futures.promise] (original) (raw)

32 Thread support library [thread]

32.9.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(); promise& operator=(promise&& rhs) noexcept; promise& operator=(const promise&) = delete;void swap(promise& other) noexcept; future<R> get_future();void set_value(see below);void set_exception(exception_ptr p);void set_value_at_thread_exit(see below);void set_exception_at_thread_exit(exception_ptr p);};template<class R> void swap(promise<R>& x, promise<R>& y) noexcept;template<class R, class Alloc> struct uses_allocator<promise<R>, Alloc>;}

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 (Table 36).

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& operator=(promise&& rhs) noexcept;

Effects: Abandons any shared state ([futures.state]) and then as ifpromise(std​::​move(rhs)).swap(*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.

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

Synchronization: Calls to this function do not introduce data races ([intro.multithread]) with calls toset_­value,set_­exception,set_­value_­at_­thread_­exit, orset_­exception_­at_­thread_­exit.

[Note 1:

Such calls need not synchronize with each other.

— _end note_]

Throws: future_­error if *this has no shared state or ifget_­future has already been called on a promise with the same shared state as *this.

Error conditions:

• future_­already_­retrieved if get_­future has already been called on a promise with the same shared state as *this.
• 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:

• future_­error if its shared state already has a stored value or exception, or
• for the first version, any exception thrown by the constructor selected to copy an object of R, or
• for the second version, any exception thrown by the constructor selected to move an object of R.

Error conditions:

• promise_­already_­satisfied if its shared state already has a stored value or exception.
• 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:

• promise_­already_­satisfied if its shared state already has a stored value or exception.
• 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:

• future_­error if its shared state already has a stored value or exception, or
• for the first version, any exception thrown by the constructor selected to copy an object of R, or
• for the second version, any exception thrown by the constructor selected to move an object of R.

Error conditions:

• promise_­already_­satisfied if its shared state already has a stored value or exception.
• 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:

• promise_­already_­satisfied if its shared state already has a stored value or exception.
• 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).