33 Concurrency support library [thread]

33.10 Futures [futures]

33.10.9 Function template async [futures.async]

The function template async provides a mechanism to launch a function potentially in a new thread and provides the result of the function in a future object with which it shares a shared state.

🔗

template<class F, class... Args>
  [[nodiscard]] future<invoke_result_t<decay_t<F>, decay_t<Args>...>>
    async(F&& f, Args&&... args);
template<class F, class... Args>
  [[nodiscard]] future<invoke_result_t<decay_t<F>, decay_t<Args>...>>
    async(launch policy, F&& f, Args&&... args);

Mandates: The following are all true:

(2.1)
is_constructible_v<decay_t<F>, F>,
(2.2)
(is_constructible_v<decay_t<Args>, Args> && ...), and
(2.3)
is_invocable_v<decay_t<F>, decay_t<Args>...>.

Effects: The first function behaves the same as a call to the second function with a policy argument of launch::async | launch::deferred and the same arguments for F and Args.

The second function creates a shared state that is associated with the returned future object.

The further behavior of the second function depends on the policy argument as follows (if more than one of these conditions applies, the implementation may choose any of the corresponding policies):

(3.1)
If launch::async is set in policy, calls invoke(auto(std::forward<F>(f)), auto(std::forward<Args>(args))...) ([func.invoke], [thread.thread.constr]) as if in a new thread of execution represented by a thread object with the values produced by auto being materialized ([conv.rval]) in the thread that called async.

Any return value is stored as the result in the shared state.

Any exception propagated from the execution of invoke(auto(std::forward<F>(f)), auto(std::forward<Args>(args))...) is stored as the exceptional result in the shared state.

The thread object is stored in the shared state and affects the behavior of any asynchronous return objects that reference that state.
(3.2)
If launch::deferred is set in policy, stores auto(std::forward<F>(f)) and auto(std::forward<Args>(args))... in the shared state.

These copies of f and args constitute a deferred function.

Invocation of the deferred function evaluates invoke(std::move(g), std::move(xyz)) where g is the stored value of auto(std::forward<F>(f)) and xyz is the stored copy of auto(std::forward<Args>(args))....

Any return value is stored as the result in the shared state.

Any exception propagated from the execution of the deferred function is stored as the exceptional result in the shared state.

The shared state is not made ready until the function has completed.

The first call to a non-timed waiting function ([futures.state]) on an asynchronous return object referring to this shared state invokes the deferred function in the thread that called the waiting function.

Once evaluation of invoke(std::move(g), std::move(xyz)) begins, the function is no longer considered deferred.
Recommended practice: If this policy is specified together with other policies, such as when using a policy value of launch::async | launch::deferred, implementations should defer invocation or the selection of the policy when no more concurrency can be effectively exploited.
(3.3)
If no value is set in the launch policy, or a value is set that is neither specified in this document nor by the implementation, the behavior is undefined.

Synchronization: The invocation of async synchronizes with the invocation of f.

The completion of the function f is sequenced before the shared state is made ready.

[Note 1:

These apply regardless of the provided policy argument, and even if the corresponding future object is moved to another thread.

However, it is possible for f not to be called at all, in which case its completion never happens.

— end note]

If the implementation chooses the launch::async policy,

(4.1)
a call to a waiting function on an asynchronous return object that shares the shared state created by this async call shall block until the associated thread has completed, as if joined, or else time out ([thread.thread.member]);
(4.2)
the associated thread completion synchronizes with ([intro.multithread]) the return from the first function that successfully detects the ready status of the shared state or with the return from the last function that releases the shared state, whichever happens first.

Returns: An object of type future<invoke_result_t<decay_t<F>, decay_t<Args>...>> that refers to the shared state created by this call to async.

[Note 2:

If a future obtained from async is moved outside the local scope, the future's destructor can block for the shared state to become ready.

— end note]

Throws: system_error if policy == launch::async and the implementation is unable to start a new thread, or std::bad_alloc if memory for the internal data structures cannot be allocated.

Error conditions:

(7.1)
resource_unavailable_try_again — if policy == launch::async and the system is unable to start a new thread.

[Example 1: int work1(int value); int work2(int value); int work(int value) { auto handle = std::async([=]{ return work2(value); }); int tmp = work1(value); return tmp + handle.get(); // #1 }

[Note 3:

Line #1 might not result in concurrency because the async call uses the default policy, which might use launch::deferred, in which case the lambda might not be invoked until the get() call; in that case, work1 and work2 are called on the same thread and there is no concurrency.

— end note]

— end example]