std::promise

C++

Language

Headers

Freestanding and hosted implementations

Named requirements

Language support library

Concepts library (C++20)

Diagnostics library

Utilities library

Strings library

Containers library

Algorithms library

Iterators library

Numerics library

Input/output library

Localizations library

Regular expressions library (C++11)

Atomic operations library (C++11)

Thread support library (C++11)

Filesystem library (C++17)

Technical Specifications

Thread support library

Threads
thread (C++11)
hardware_destructive_interference_sizehardware_constructive_interference_size (C++17)(C++17)
this_thread namespace
get_id (C++11) yield (C++11)	sleep_for (C++11) sleep_until (C++11)
Mutual exclusion
mutex (C++11) recursive_mutex (C++11) shared_mutex (C++17)	timed_mutex (C++11) recursive_timed_mutex (C++11) shared_timed_mutex (C++14)
Generic lock management
lock_guard (C++11) scoped_lock (C++17) unique_lock (C++11) shared_lock (C++14) defer_lock_ttry_to_lock_tadopt_lock_t (C++11)(C++11)(C++11)	lock (C++11) try_lock (C++11) defer_locktry_to_lockadopt_lock (C++11)(C++11)(C++11) once_flag (C++11) call_once (C++11)
Condition variables
condition_variable (C++11)
condition_variable_any (C++11)
notify_all_at_thread_exit (C++11)
cv_status (C++11)
Futures
promise (C++11) future (C++11) shared_future (C++11) packaged_task (C++11) async (C++11)	launch (C++11) future_status (C++11) future_error (C++11) future_category (C++11) future_errc (C++11)

std::promise

Member functions

promise::promise

promise::~promise

promise::operator=

promise::swap

Getting the result

promise::get_future

Setting the result

promise::set_value

promise::set_value_at_thread_exit

promise::set_exception

promise::set_exception_at_thread_exit

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.

Member functions

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

Non-member functions

std::swap(std::promise) (C++11)

specializes the std::swap algorithm (function template)

Helper classes

std::uses_allocator<std::promise> (C++11)

specializes the std::uses_allocator type trait (class template specialization)

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>
#include <chrono>

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));
    accumulate_future.wait();  // wait for result
    std::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