GeezerVison

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

GeezerVison is showing cplusplus.com — std::async

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

function template

std::async

unspecified policy (1)

template <class Fn, class... Args>  future<typename result_of<Fn(Args...)>::type>    async (Fn&& fn, Args&&... args);

specific policy (2)

template <class Fn, class... Args>  future<typename result_of<Fn(Args...)>::type>    async (launch policy, Fn&& fn, Args&&... args);

Call function asynchronously

Calls fn (with args as arguments) at some point, returning without waiting for the execution of fn to complete.

The value returned by fn can be accessed through the future object returned (by calling its member future::get).

The second version (2) lets the caller select a specific launching policy, while the first version (1) uses automatic selection, as if calling (2) with launch::async|launch::deferred as policy.

The function temporarily stores in the shared state either the threading handler used or decay copies of fn and args (as a deferred function) without making it ready. Once the execution of fn is completed, the shared state contains the value returned by fn and is made ready.

Parameters

policy

A bitmask value of type launch indicating the launching policy:

policy	description
`launch::async`	Asynchronous: Launches a new thread to call `fn` (as if a `thread` object is constructed with `fn` and `args` as arguments, and accessing the shared state of the returned `future` joins it).
`launch::deferred`	Deferred: The call to `fn` is deferred until the shared state of the returned `future` is accessed (with `wait` or `get`). At that point, `fn` is called and the function is no longer considered deferred. When this call returns, the shared state of the returned `future` is made ready.
`launch::async\|launch::deferred`	Automatic: The function chooses the policy automatically (at some point). This depends on the system and library implementation, which generally optimizes for the current availability of concurrency in the system.

Particular library implementations may support additional launching policies, with the proper label defined in type launch. Combining multiple values is possible, in which case, the function automatically chooses one among them.

fn

A pointer to function, pointer to member, or any kind of move-constructible function object (i.e., an object whose class defines operator(), including closures and function objects).
The function uses a decay copy of this argument.
The return value of fn is stored as the shared state to be retrieved by the future object returned by async.
If fn throws, the exception is set in the shared state to be retrieved by the future object.

args...

Arguments passed to the call to fn (if any). Their types shall be move-constructible.
If fn is a member pointer, the first argument shall be an object for which that member is defined (or a reference, or a pointer to it).
The function uses decay copies of these arguments.

Fn and Args... are template parameters: if implicitly deduced, these are the proper lvalue or rvalue reference types of the arguments. Note though, that the function uses decay copies of fn and args... (see std::ref for a wrapper class that makes references copyable).

Return value

A future object whose shared state is made ready when the execution of fn ends. The value retrieved by its member future::get is the value returned by fn (if any).

When launch::async is selected, the future returned is linked to the end of the thread created, even if its shared state is never accessed: in this case, its destructor synchronizes with the return of fn. Therefore, the return value shall not be disregarded for asynchronous behavior, even when fn returns void.

result_of::type is the type returned by Fn when called with arguments of the types in Args.

Example

// async example
#include <iostream>       // std::cout
#include <future>         // std::async, std::future

// a non-optimized way of checking for prime numbers:
bool is_prime (int x) {
  std::cout << "Calculating. Please, wait...\n";
  for (int i=2; i<x; ++i) if (x%i==0) return false;
  return true;
}

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

  std::cout << "Checking whether 313222313 is prime.\n";
  // ...

  bool ret = fut.get();      // waits for is_prime to return

  if (ret) std::cout << "It is prime!\n";
  else std::cout << "It is not prime.\n";

  return 0;
}

Possible output (the first two lines may be in a different order, or scrambled):


Checking whether 313222313 is prime.
Calculating. Please, wait...
It is prime!

Data races

The arguments are accessed to create decay copies.
All visible side effects are synchronized between the call to async and the call to fn, and between its return point and the access to the returned future's share state.

Exception safety

Basic guarantee: if an exception is thrown, all objects involved are left in a valid state.

This member function throws an exception on the following conditions:

exception type	error condition	description
`system_error`	`errc::resource_unavailable_try_again`	The system is unable to start a new thread

Depending on the library implementation, this member function may also throw exceptions to report other situations.

If fn throws an exception, it is caught and stored in the shared state accessed by the returned future.

classes

enum classes