class template
<future>

std::future

template <class T>  future;
template <class R&> future<R&>;     // specialization : T is a reference type (R&)
template <>         future<void>;   // specialization : T is void
Future
A future is an object that can retrieve a value from some provider object or function, properly synchronizing this access if in different threads.

"Valid" futures are future objects associated to a shared state, and are constructed by calling one of the following functions:

future objects are only useful when they are valid. Default-constructed future objects are not valid (unless move-assigned a valid future).

Calling future::get on a valid future blocks the thread until the provider makes the shared state ready (either by setting a value or an exception to it). This way, two threads can be synchronized by one waiting for the other to set a value.

The lifetime of the shared state lasts at least until the last object with which it is associated releases it or is destroyed. Therefore, if associated to a future, the shared state can survive the object from which it was obtained in the first place (if any).

Member functions

(constructor)
Construct future (public member function )
(destructor)
Destroy future (public member function )
operator=
Move-assign future (public member function )
share
Get shared future (public member function )
get
Get value (public member function )
valid
Check for valid shared state (public member function )
wait
Wait for ready (public member function )
wait_for
Wait for ready during time span (public member function )
wait_until
Wait for ready until time point (public member function )

Template specializations

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

They operate in the same way as the unspecialized template, except for the return value of their future::get member function.

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
25
26
27
28
 
// future example
#include <iostream>       // std::cout
#include <future>         // std::async, std::future
#include <chrono>         // std::chrono::milliseconds

// a non-optimized way of checking for prime numbers:
bool is_prime (int x) {
  for (int i=2; i<x; ++i) if (x%i==0) return false;
  return true;
}

int main ()
{
  // call function asynchronously:
  std::future<bool> fut = std::async (is_prime,444444443); 

  // do something while waiting for function to set future:
  std::cout << "checking, please wait";
  std::chrono::milliseconds span (100);
  while (fut.wait_for(span)==std::future_status::timeout)
    std::cout << '.' << std::flush;

  bool x = fut.get();     // retrieve return value

  std::cout << "\n444444443 " << (x?"is":"is not") << " prime.\n";

  return 0;
}


Possible output (may take more or less time):

checking, please wait........................
444444443 is prime.

C++