32 Thread support library [thread]
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 if
promise(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 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]
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:
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).