From cppreference.com
Defined in header
template<classR>classpromise; (1) (since C++11)template<classR>classpromise<R&>; (2) (since C++11)template<>classpromise<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
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
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
) the successful return from any function that is waiting on the shared state (such as
). Concurrent access to the same shared state may conflict otherwise: for example multiple callers of
must either all be read-only or provide external synchronization.
Member functions
constructs the promise object
(public member function)
destructs the promise object
(public member function)
assigns the shared state
(public member function)
swaps two promise objects
(public member function)
Getting the result
returns a
associated with the promised result
(public member function)
Setting the result
sets the result to specific value
(public member function)
sets the result to specific value while delivering the notification only at thread exit
(public member function)
sets the result to indicate an exception
(public member function)
sets the result to indicate an exception while delivering the notification only at thread exit
(public member function)
Non-member functions
Helper classes
Example
This example shows how promise<int> can be used as signals between threads.
Run this code
#include<chrono>#include<future>#include<iostream>#include<numeric>#include<thread>#include<vector>voidaccumulate(std::vector<int>::iteratorfirst,std::vector<int>::iteratorlast,std::promise<int>accumulate_promise){intsum=std::accumulate(first,last,0);accumulate_promise.set_value(sum);// Notify future}voiddo_work(std::promise<void>barrier){std::this_thread::sleep_for(std::chrono::seconds(1));barrier.set_value();}intmain(){// Demonstrate using promise<int> to transmit a result between threads.std::vector<int>numbers={1,2,3,4,5,6};std::promise<int>accumulate_promise;std::future<int>accumulate_future=accumulate_promise.get_future();std::threadwork_thread(accumulate,numbers.begin(),numbers.end(),std::move(accumulate_promise));// future::get() will wait until the future has a valid result and retrieves it.// Calling wait() before get() is not needed// accumulate_future.wait(); // wait for resultstd::cout<<"result="<<accumulate_future.get()<<'\n';work_thread.join();// wait for thread completion// Demonstrate using promise<void> to signal state between threads.std::promise<void>barrier;std::future<void>barrier_future=barrier.get_future();std::threadnew_work_thread(do_work,std::move(barrier));barrier_future.wait();new_work_thread.join();}Output:
result=21