The function templatestd::async runs the functionf asynchronously (potentially in a separate thread which might be a part of a thread pool) and returns astd::future that will eventually hold the result of that function call.

The return type ofstd::async isstd::future<V>, whereV is:

The call tostd::asyncsynchronizes with the call tof, and the completion off issequenced before making the shared state ready.

[edit]Parameters

[edit]Return value

std::future referring to the shared state created by this call tostd::async.

[edit]Launch policies

[edit]Async invocation

If theasync flag is set, i.e.(policy&std::launch::async)!=0, thenstd::async calls

as if in a new thread of execution represented by astd::thread object.

If the functionf returns a value or throws an exception, it is stored in the shared state accessible through thestd::future thatstd::async returns to the caller.

[edit]Deferred invocation

If thedeferred flag is set (i.e.(policy&std::launch::deferred)!=0), thenstd::async stores

Lazy evaluation is performed:

• The first call to a non-timed wait function on thestd::future thatstd::async returned to the caller will evaluateINVOKE(std::move(g), std::move(xyz)) in the thread that called the waiting function (which does not have to be the thread that originally calledstd::async), where

• The result or exception is placed in the shared state associated with the returnedstd::future and only then it is made ready. All further accesses to the samestd::future will return the result immediately.

[edit]Other policies

If neitherstd::launch::async norstd::launch::deferred, nor any implementation-defined policy flag is set inpolicy, the behavior is undefined.

[edit]Policy selection

If more than one flag is set, it is implementation-defined which policy is selected. For the default (both thestd::launch::async andstd::launch::deferred flags are set inpolicy), standard recommends (but does not require) utilizing available concurrency, and deferring any additional tasks.

If thestd::launch::async policy is chosen,

• a call to a waiting function on an asynchronous return object that shares the shared state created by thisstd::async call blocks until the associated thread has completed, as if joined, or else time out; and
• the associated thread completionsynchronizes-with the successful return from the first function that is waiting on the shared state, or with the return of the last function that releases the shared state, whichever comes first.

[edit]Exceptions

Throws

• std::bad_alloc, if the memory for the internal data structures cannot be allocated, or
• std::system_error with error conditionstd::errc::resource_unavailable_try_again, ifpolicy==std::launch::async and the implementation is unable to start a new thread.
  • Ifpolicy isstd::launch::async|std::launch::deferred or has additional bits set, it will fall back to deferred invocation or the implementation-defined policies in this case.

[edit]Notes

The implementation may extend the behavior of the first overload ofstd::async by enabling additional (implementation-defined) bits in the default launch policy.

Examples of implementation-defined launch policies are the sync policy (execute immediately, within thestd::async call) and the task policy (similar tostd::async, but thread-locals are not cleared)

If thestd::future obtained fromstd::async is not moved from or bound to a reference, the destructor of thestd::future will block at the end of the full expression until the asynchronous operation completes, essentially making code such as the following synchronous:

std::async(std::launch::async,[]{ f();});// temporary's dtor waits for f()std::async(std::launch::async,[]{ g();});// does not start until f() completes

Note that the destructors ofstd::futures obtained by means other than a call tostd::async never block.

[edit]Example

#include <algorithm>#include <future>#include <iostream>#include <mutex>#include <numeric>#include <string>#include <vector> std::mutex m; struct X{void foo(int i,conststd::string& str){std::lock_guard<std::mutex> lk(m);std::cout<< str<<' '<< i<<'\n';} void bar(conststd::string& str){std::lock_guard<std::mutex> lk(m);std::cout<< str<<'\n';} int operator()(int i){std::lock_guard<std::mutex> lk(m);std::cout<< i<<'\n';return i+10;}}; template<typename RandomIt>int parallel_sum(RandomIt beg, RandomIt end){auto len= end- beg;if(len<1000)returnstd::accumulate(beg, end,0);     RandomIt mid= beg+ len/2;auto handle= std::async(std::launch::async,                             parallel_sum<RandomIt>, mid, end);int sum= parallel_sum(beg, mid);return sum+ handle.get();} int main(){std::vector<int> v(10000,1);std::cout<<"The sum is "<< parallel_sum(v.begin(), v.end())<<'\n';     X x;// Calls (&x)->foo(42, "Hello") with default policy:// may print "Hello 42" concurrently or defer executionauto a1= std::async(&X::foo,&x,42,"Hello");// Calls x.bar("world!") with deferred policy// prints "world!" when a2.get() or a2.wait() is calledauto a2= std::async(std::launch::deferred,&X::bar, x,"world!");// Calls X()(43); with async policy// prints "43" concurrentlyauto a3= std::async(std::launch::async, X(),43);    a2.wait();// prints "world!"std::cout<< a3.get()<<'\n';// prints "53"}// if a1 is not done at this point, destructor of a1 prints "Hello 42" here

The sum is 1000043world!53Hello 42

[edit]Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

1. ↑The move-constructibility is already indirectly required bystd::is_constructible_v.

[edit]See also

• In other languages

• Deutsch
• Español
• Français
• Italiano
• 日本語
• Português
• Русский
• 中文