class template
<future>

std::promise

template <class T>  promise;
template <class R&> promise<R&>;     // specialization : T is a reference type (R&)
template <>         promise<void>;   // specialization : T is void
Promise
A promise is an object that can store a value of type T to be retrieved by a future object (possibly in another thread), offering a synchronization point.

On construction, promise objects are associated to a new shared state on which they can store either a value of type T or an exception derived from std::exception.

This shared state can be associated to a future object by calling member get_future. After the call, both objects share the same shared state:
- The promise object is the asynchronous provider and is expected to set a value for the shared state at some point.
- The future object is an asynchronous return object that can retrieve the value of the shared state, waiting for it to be ready, if necessary.

The lifetime of the shared state lasts at least until the last object with which it is associated releases it or is destroyed. Therefore it can survive the promise object that obtained it in the first place if associated also to a future.

Member functions

(constructor)
Construct promise (public member function )
(destructor)
Destroy promise (public member function )
operator=
Move-assign promise (public member function )
get_future
Get future (public member function )
set_value
Set value (public member function )
set_exception
Set exception (public member function )
set_value_at_thread_exit
Set value at thread exit (public member function )
set_exception_at_thread_exit
Set exception at thread exit (public member function )
swap
Swap shared states (public member function )

Non-member function overaloas

swap (promise)
Swap promises (function template )

Non-member class specializations

uses_allocator<promise>
Uses allocator for promise (class template )

Template specializations

Two specific promise specializations are declared in <future>:
1
2
 
template <class R&> promise<R&>;     // specialization : T is a reference type (R&)
template <>         promise<void>;   // specialization : T is void

They operate in the same way as the unspecialized template, except for the argument their set_value and set_value_at_thread_exit member functions take.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
 
// promise example
#include <iostream>       // std::cout
#include <functional>     // std::ref
#include <thread>         // std::thread
#include <future>         // std::promise, std::future

void print_int (std::future<int>& fut) {
  int x = fut.get();
  std::cout << "value: " << x << '\n';
}

int main ()
{
  std::promise<int> prom;                      // create promise

  std::future<int> fut = prom.get_future();    // engagement with future

  std::thread th1 (print_int, std::ref(fut));  // send future to new thread

  prom.set_value (10);                         // fulfill promise
                                               // (synchronizes with getting the future)
  th1.join();
  return 0;
}


Output:

value: 10

C++