Difference between revisions of "cpp/thread/promise"
From cppreference.com
m |
m (fix case of sentence start word) |
||
| Line 21: | Line 21: | ||
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: | 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. | + | * ''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 {{c|std::async}} which is not yet ready, this operation does not block. | * ''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 {{c|std::async}} which is not yet ready, this operation does not block. | ||
* ''abandon'': the promise stores the exception of type {{lc|std::future_error}} with error code {{lc|std::future_errc::broken_promise}}, makes the shared state ''ready'', and then ''releases'' it. | * ''abandon'': the promise stores the exception of type {{lc|std::future_error}} with error code {{lc|std::future_errc::broken_promise}}, makes the shared state ''ready'', and then ''releases'' it. | ||
Revision as of 04:15, 7 December 2014
| Defined in header <future>
|
||
| template< class T > class promise; |
(1) | (since C++11) |
| template< class T > class promise<T&>; |
(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.
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 |
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) | |
Non-member functions
| (C++11) |
specializes the std::swap algorithm (function template) |
Helper classes
| specializes the std::uses_allocator type trait (class template specialization) |
