std::promise (3) - Linux Manuals
Defined in header <future>
template< class R > class promise; (1) (since C++11)
template< class R > class promise<R&>; (2) (since C++11)
template<> class promise<void>; (3) (since C++11)
1) base template
2) non-void specialization, used to communicate objects between threads
3) void specialization, used to communicate stateless events
The class template std::promise provides a facility to store a value or an exception that is later acquired asynchronously via a std::future object created by the std::promise object. Note that the std::promise object is meant to be used only once.
Each promise is associated with a shared state, which contains some state information and a result which may be not yet evaluated, evaluated to a value (possibly void) or evaluated to an exception. A promise may do three things with the shared state:
* make ready: the promise stores the result or the exception in the shared state. Marks the state ready and unblocks any thread waiting on a future associated with the shared state.
* release: the promise gives up its reference to the shared state. If this was the last such reference, the shared state is destroyed. Unless this was a shared state created by std::async which is not yet ready, this operation does not block.
* abandon: the promise stores the exception of type std::future_error with error code std::future_errc::broken_promise, makes the shared state ready, and then releases it.
The promise is the "push" end of the promise-future communication channel: the operation that stores a value in the shared state synchronizes-with (as defined in std::memory_order) the successful return from any function that is waiting on the shared state (such as std::future::get). Concurrent access to the same shared state may conflict otherwise: for example multiple callers of std::shared_future::get must either all be read-only or provide external synchronization.
constructor (public member function)
destructor (public member function)
operator= (public member function)
swap (public member function)
Getting the result
get_future (public member function)
Setting the result
set_value (public member function)
set_value_at_thread_exit (public member function)
set_exception (public member function)
set_exception_at_thread_exit (public member function)
std::swap(std::promise) specializes the std::swap algorithm
std::uses_allocator<std::promise> specializes the std::uses_allocator type trait
This example shows how promise<int> can be used as signals between threads.
// Run this code