##### cppreference.com

##### Search

Create account

##### Namespaces

- Page
- Discussion

##### Variants

##### Views

- View
- Edit
- History

##### Actions

# std::async

From cppreference.com
< cpp‎ | thread

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 executed in another 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` executes the function `f` on a separate thread of execution as if spawned 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.

- (C++14) If neither std::launch::async nor std::launch::deferred, nor any implementation-defined policy flag is set in `policy`, the behavior is undefined.

### [edit] 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

### [edit] Return value

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

### [edit] 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.

### [edit] 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.

### [edit] 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

Retrieved from "http://en.cppreference.com/mwiki/index.php?title=cpp/thread/async&oldid=66196"