std::promise - cppreference.com

##### cppreference.com

##### Search

Create account

##### Namespaces

- Page
- Discussion

##### Variants

##### Views

- View
- Edit
- History

##### Actions

# std::promise

From cppreference.com
< cpp‎ | thread

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.

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.

### [edit] Member functions

(constructor) | constructs the promise object (public member function) [edit]
(destructor) | destructs the promise object (public member function) [edit]
operator= | assigns the shared state (public member function) [edit]
swap | swaps two promise objects (public member function) [edit]
##### Getting the result
get_future | returns a `future` associated with the promised result (public member function) [edit]
##### Setting the result
set_value | sets the result to specific value (public member function) [edit]
set_value_at_thread_exit | sets the result to specific value while delivering the notification only at thread exit (public member function) [edit]
set_exception | sets the result to indicate an exception (public member function) [edit]
set_exception_at_thread_exit | sets the result to indicate an exception while delivering the notification only at thread exit (public member function) [edit]

### [edit] Non-member functions

std::swap(std::promise) (C++11) | specializes the std::swap algorithm (function template) [edit]

### [edit] Helper classes

std::uses_allocator<std::promise> (C++11) | specializes the std::uses_allocator type trait (class template specialization) [edit]

### [edit] Example

This example shows how `promise<int>` can be used as signals between threads.

Run this code

    #include <vector>
    #include <thread>
    #include <future>
    #include <numeric>
    #include <iostream>

    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
    }

    int main()
    {
        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));
        accumulate_future.wait();  // wait for result
        std::cout << "result=" << accumulate_future.get() << '\n';
        work_thread.join();  // wait for thread completion
    }

Output:

    result=21

Retrieved from "http://en.cppreference.com/mwiki/index.php?title=cpp/thread/promise&oldid=81978"