32 Thread support library [thread]

32.9 Futures [futures]

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();

    // 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>
    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();

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();

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 to set_value, set_exception, set_value_at_thread_exit, or set_exception_at_thread_exit.

[ Note

Such calls need not synchronize with each other.

— end note

]

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:

(15.1)
future_already_retrieved if get_future has already been called on a promise with the same shared state as *this.
(15.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:

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

Error conditions:

(18.1)
promise_already_satisfied if its shared state already has a stored value or exception.
(18.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:

(22.1)
promise_already_satisfied if its shared state already has a stored value or exception.
(22.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:

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

Error conditions:

(25.1)
promise_already_satisfied if its shared state already has a stored value or exception.
(25.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:

(29.1)
promise_already_satisfied if its shared state already has a stored value or exception.
(29.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).