std::promise
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) |
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.
Contents |
[edit]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 future 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) | |
[edit]Non-member functions
(C++11) | specializes the std::swap algorithm (function template) |
[edit]Helper classes
| specializes the std::uses_allocator type trait (class template specialization) |
[edit]Example
This example shows how promise<int> can be used as signals between threads.
#include <chrono>#include <future>#include <iostream>#include <numeric>#include <thread>#include <vector> void accumulate(std::vector<int>::iterator first, std::vector<int>::iterator last, std::promise<int> accumulate_promise){int sum =std::accumulate(first, last, 0); accumulate_promise.set_value(sum);// Notify future} void do_work(std::promise<void> barrier){std::this_thread::sleep_for(std::chrono::seconds(1)); barrier.set_value();} int main(){// 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::thread work_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::thread new_work_thread(do_work, std::move(barrier)); barrier_future.wait(); new_work_thread.join();}
Output:
result=21
