GeezerVison

The World Wide Web, restored to 800 pixels of glory.

GeezerVison is showing cplusplus.com — std::future

Reference

C library:
- <cassert> (assert.h)
- <cctype> (ctype.h)
- <cerrno> (errno.h)
- C++11
  <cfenv> (fenv.h)
- <cfloat> (float.h)
- C++11
  <cinttypes> (inttypes.h)
- <ciso646> (iso646.h)
- <climits> (limits.h)
- <clocale> (locale.h)
- <cmath> (math.h)
- <csetjmp> (setjmp.h)
- <csignal> (signal.h)
- <cstdarg> (stdarg.h)
- C++11
  <cstdbool> (stdbool.h)
- <cstddef> (stddef.h)
- C++11
  <cstdint> (stdint.h)
- <cstdio> (stdio.h)
- <cstdlib> (stdlib.h)
- <cstring> (string.h)
- C++11
  <ctgmath> (tgmath.h)
- <ctime> (time.h)
- C++11
  <cuchar> (uchar.h)
- <cwchar> (wchar.h)
- <cwctype> (wctype.h)
Containers:
- C++11
  <array>
- <deque>
- C++11
  <forward_list>
- <list>
- <map>
- <queue>
- <set>
- <stack>
- C++11
  <unordered_map>
- C++11
  <unordered_set>
- <vector>
Input/Output:
- <fstream>
- <iomanip>
- <ios>
- <iosfwd>
- <iostream>
- <istream>
- <ostream>
- <sstream>
- <streambuf>
Multi-threading:
- C++11
  <atomic>
- C++11
  <condition_variable>
- C++11
  <future>
- C++11
  <mutex>
- C++11
  <thread>
Other:
- <algorithm>
- <bitset>
- C++11
  <chrono>
- C++11
  <codecvt>
- <complex>
- <exception>
- <functional>
- C++11
  <initializer_list>
- <iterator>
- <limits>
- <locale>
- <memory>
- <new>
- <numeric>
- C++11
  <random>
- C++11
  <ratio>
- C++11
  <regex>
- <stdexcept>
- <string>
- C++11
  <system_error>
- C++11
  <tuple>
- C++11
  <type_traits>
- C++11
  <typeindex>
- <typeinfo>
- <utility>
- <valarray>

<future>

classes
- C++11
  future
- C++11
  future_error
- C++11
  packaged_task
- C++11
  promise
- C++11
  shared_future
enum classes
- C++11
  future_errc
- C++11
  future_status
- C++11
  launch
functions
- C++11
  async
- C++11
  future_category

future

C++11
future::~future
C++11
future::future
member functions
- C++11
  future::get
- C++11
  future::operator=
- C++11
  future::share
- C++11
  future::valid
- C++11
  future::wait
- C++11
  future::wait_for
- C++11
  future::wait_until

class template

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

// 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.

You are visitor 01402503 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.

classes

enum classes

functions

member functions

std::future

Member functions

Template specializations

Example