std::async

 

C++

Language

Standard library headers

Concepts

Utilities library

Strings library

Containers library

Algorithms library

Iterators library

Numerics library

Input/output library

Localizations library

Regular expressions library (C++11)

Atomic operations library (C++11)

Thread support library (C++11)

 

Thread support library

Threads
thread (C++11)
this_thread namespace
get_id (C++11) yield (C++11)	sleep_for (C++11) sleep_until (C++11)
Mutual exclusion
mutex (C++11) timed_mutex (C++11)	recursive_mutex (C++11) recursive_timed_mutex (C++11)
Generic lock management
lock_guard (C++11) unique_lock (C++11) defer_lock_t try_to_lock_t adopt_lock_t (C++11) (C++11) (C++11)	lock (C++11) try_lock (C++11) defer_lock try_to_lock adopt_lock (C++11) (C++11) (C++11)
Condition variables
condition_variable (C++11)
condition_variable_any (C++11)
notify_all_at_thread_exit (C++11)
cv_status (C++11)
Futures
promise (C++11) future (C++11) shared_future (C++11) packaged_task (C++11) async (C++11)	launch (C++11) future_status (C++11) future_error (C++11) future_category (C++11) future_errc (C++11)

 

Defined in header <future>
template< class Function, class... Args> std::future<typename std::result_of<Function(Args...)>::type>     async( Function&& f, Args&&... args );	(1)	(since C++11)
template< class Function, class... Args > std::future<typename std::result_of<Function(Args...)>::type>     async( std::launch policy, Function&& f, Args&&... args );	(2)	(since C++11)

The template function async runs the function f asynchronously (potentially in a separate thread) and returns a std::future that will eventually hold the result of that function call.

1) Behaves the same as async(std::launch::async | std::launch::deferred, f, args...). In other words, f may be started in a new thread or it may be run synchronously when the resulting std::future is queried for a value.

2) Calls a function f with arguments args according to a specific launch policy policy:

• If the async flag is set (i.e. policy & std::launch::async != 0), then async spawns a new thread of execution as if by std::thread(f, args...), except that if the function f returns a value or throws an exception, it is stored in the shared state accessible through the std::future that async returns to the caller.

• If the deferred flag is set (i.e. policy & std::launch::deferred != 0), then async converts args... the same way as by std::thread constructor, but does not spawn a new thread of execution. Instead, lazy evaluation is performed: the first call to a non-timed wait function on the std::future that async returned to the caller will cause f(args...) to be executed in the current thread. All further accesses to the same std::future will return the result immediately.

• If both the std::launch::async and std::launch::deferred flags are set in policy, it is up to the implementation whether to perform asynchronous execution or lazy evaluation.

Parameters

f	-	function or function object to call
args...	-	parameters to pass to f
policy	-	bitmask value, where individual bits control the allowed methods of execution Bit Explanation std::launch::async enable asynchronous evaluation std::launch::deferred enable lazy evaluation

Return value

std::future referring to the return value of the function.

Exceptions

Throws std::system_error with error condition std::errc::resource_unavailable_try_again if the launch policy is std::launch::async and the implementation is unable to start a new thread.

Notes

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

One drawback with the current definition of std::async is that the associated state of an operation launched by std::async can cause the returned std::future's destructor to block until the operation is complete. This can limit composability and result in code that appears to run in parallel but in reality runs sequentially. For example:

run this code

{
    std::async(std::launch::async, []{ f(); });
    std::async(std::launch::async, []{ g(); });  // does not run until f() completes
}

In the above code, f() and g() run sequentially because the destruction of the returned future blocks until each operation has finished.

Example

run this code

#include <iostream>
#include <vector>
#include <algorithm>
#include <numeric>
#include <future>
 
template <typename RAIter>
int parallel_sum(RAIter beg, RAIter end)
{
    typename RAIter::difference_type len = end-beg;
    if(len < 1000)
        return std::accumulate(beg, end, 0);
 
    RAIter mid = beg + len/2;
    auto handle = std::async(std::launch::async,
                              parallel_sum<RAIter>, 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';
}

Output:

The sum is 10000