promise Class
Describes an asynchronous provider.
Syntax
template <class Ty>
class promise;
Members
Public Constructors
| Name | Description |
|---|---|
| promise | Constructs a promise object. |
Public Methods
| Name | Description |
|---|---|
| get_future | Returns a future associated with this promise. |
| set_exception | Atomically sets the result of this promise to indicate an exception. |
| set_exception_at_thread_exit | Atomically sets the result of this promise to indicate an exception, and delivers the notification only after all thread-local objects in the current thread have been destroyed (usually at thread exit). |
| set_value | Atomically sets the result of this promise to indicate a value. |
| set_value_at_thread_exit | Atomically sets the result of this promise to indicate a value, and delivers the notification only after all thread-local objects in the current thread have been destroyed (usually at thread exit). |
| swap | Exchanges the associated asynchronous state of this promise with that of a specified promise object. |
Public Operators
| Name | Description |
|---|---|
| promise::operator= | Assignment of the shared state of this promise object. |
Inheritance Hierarchy
promise
Requirements
Header: <future>
Namespace: std
promise::get_future
Returns a future object that has the same associated asynchronous state as this promise.
future<Ty> get_future();
Remarks
If the promise object is empty, this method throws a future_error that has an error_code of no_state.
If this method has already been called for a promise object that has the same associated asynchronous state, the method throws a future_error that has an error_code of future_already_retrieved.
promise::operator=
Transfers the associated asynchronous state from a specified promise object.
promise& operator=(promise&& Other) noexcept;
Parameters
Other
A promise object.
Return Value
*this
Remarks
This operator transfers the associated asynchronous state from Other. After the transfer, Other is empty.
promise::promise Constructor
Constructs a promise object.
promise();
template <class Alloc>
promise(allocator_arg_t, const Alloc& Al);
promise(promise&& Other) noexcept;
Parameters
Al
A memory allocator. For more information about allocators, see <allocators>.
Other
A promise object.
Remarks
The first constructor constructs an empty promise object.
The second constructor constructs an empty promise object and uses Al for memory allocation.
The third constructor constructs a promise object and transfers the associated asynchronous state from Other, and leaves Other empty.
promise::set_exception
Atomically stores an exception as the result of this promise object and sets the associated asynchronous state to ready.
void set_exception(exception_ptr Exc);
Parameters
Exc
An exception_ptr that's stored by this method as the exception result.
Remarks
If the promise object has no associated asynchronous state, this method throws a future_error that has an error code of no_state.
If set_exception, set_exception_at_thread_exit, set_value, or set_value_at_thread_exit has already been called for a promise object that has the same associated asynchronous state, this method throws a future_error that has an error code of promise_already_satisfied.
As a result of this method, any threads that are blocked on the associated asynchronous state become unblocked.
promise::set_exception_at_thread_exit
Atomically sets the result of this promise to indicate an exception, delivering the notification only after all thread-local objects in the current thread have been destroyed (usually at thread exit).
void set_exception_at_thread_exit(exception_ptr Exc);
Parameters
Exc
An exception_ptr that's stored by this method as the exception result.
Remarks
If the promise object has no associated asynchronous state, this method throws a future_error that has an error code of no_state.
If set_exception, set_exception_at_thread_exit, set_value, or set_value_at_thread_exit has already been called for a promise object that has the same associated asynchronous state, this method throws a future_error that has an error code of promise_already_satisfied.
In contrast to set_exception, this method doesn't set the associated asynchronous state to ready until after all thread-local objects in the current thread have been destroyed. Typically, threads that are blocked on the associated asynchronous state aren't unblocked until the current thread exits.
promise::set_value
Atomically stores a value as the result of this promise object and sets the associated asynchronous state to ready.
void promise::set_value(const Ty& Val);
void promise::set_value(Ty&& Val);
void promise<Ty&>::set_value(Ty& Val);
void promise<void>::set_value();
Parameters
Val
The value to be stored as the result.
Remarks
If the promise object has no associated asynchronous state, this method throws a future_error that has an error code of no_state.
If set_exception, set_exception_at_thread_exit, set_value, or set_value_at_thread_exit has already been called for a promise object that has the same associated asynchronous state, this method throws a future_error that has an error code of promise_already_satisfied.
As a result of this method, any threads that are blocked on the associated asynchronous state become unblocked.
The first method also throws any exception that is thrown when Val is copied into the associated asynchronous state. In this situation, the associated asynchronous state isn't set to ready.
The second method also throws any exception that is thrown when Val is moved into the associated asynchronous state. In this situation, the associated asynchronous state isn't set to ready.
For the partial specialization promise<Ty&>, the stored value is in effect a reference to Val.
For the specialization promise<void>, no stored value exists.
promise::set_value_at_thread_exit
Atomically stores a value as the result of this promise object.
void promise::set_value_at_thread_exit(const Ty& Val);
void promise::set_value_at_thread_exit(Ty&& Val);
void promise<Ty&>::set_value_at_thread_exit(Ty& Val);
void promise<void>::set_value_at_thread_exit();
Parameters
Val
The value to be stored as the result.
Remarks
If the promise object has no associated asynchronous state, this method throws a future_error that has an error code of no_state.
If set_exception, set_exception_at_thread_exit, set_value, or set_value_at_thread_exit has already been called for a promise object that has the same associated asynchronous state, this method throws a future_error that has an error code of promise_already_satisfied.
In contrast to set_value, the associated asynchronous state isn't set to ready until after all thread-local objects in the current thread have been destroyed. Typically, threads that are blocked on the associated asynchronous state aren't unblocked until the current thread exits.
The first method also throws any exception that is thrown when Val is copied into the associated asynchronous state.
The second method also throws any exception that is thrown when Val is moved into the associated asynchronous state.
For the partial specialization promise<Ty&>, the stored value is effectively a reference to Val.
For the specialization promise<void>, no stored value exists.
promise::swap
Exchanges the associated asynchronous state of this promise object with that of a specified object.
void swap(promise& Other) noexcept;
Parameters
Other
A promise object.
See also
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for