std::async function template

`std::async` function template

std::experimental::async is a simple way of running self-contained asynchronous tasks to make use of the available hardware concurrency. A call to std::experimental::async returns a std::experimental::future that will contain the result of the task. Depending on the launch policy, the task is either run asynchronously on its own thread or synchronously on whichever thread calls the wait() or get() member functions on that future.

enum class launch
{
    async,deferred,sync=deferred,any=async|deferred
};

template<typename Callable,typename ... Args>
future<result_of<Callable(Args...)>::type>
async(Callable&& func,Args&& ... args);

template<typename Callable,typename ... Args>
future<result_of<Callable(Args...)>::type>
async(launch policy,Callable&& func,Args&& ... args);

	Note
	The values `std::launch::sync` and `std::launch::any` are provided for backwards compatibility only. New programs should use `std::launch::deferred` and `std::launch::async \| std::launch::deferred` respectively.

Preconditions:

The expression INVOKE(func,args) is valid for the supplied values of func and args. Callable and every member of Args is MoveConstructible.

Effects:

Constructs copies of func and args... in internal storage (denoted by fff and xyz... respectively).

If policy is std::launch::async then runs INVOKE(fff,xyz...) on its own thread. The returned std::experimental::future will become ready when this thread is complete, and will hold either the return value or exception thrown by the function invocation. The destructor of the last future object associated with the asynchronous state of the returned std::experimental::future shall block until the future is ready.

If policy is std::launch::deferred then fff and xyz... are stored in the returned std::experimental::future as a deferred function call. The first call to the wait() or get() member functions on a future that shares the same associated state will execute INVOKE(fff,xyz...) synchronously on the thread that called wait() or get().

The value returned or exception thrown by the execution of INVOKE(fff,xyz...) will be returned from a call to get() on that std::experimental::future.

If policy is std::launch::async | std::launch::deferred or the policy argument is omitted then the implementation will choose between std::launch::async or std::launch::deferred based on an internal algorithm designed to take advantage of the available hardware concurrency without excessive oversubscription.

In all cases, the std::experimental::async call returns immediately.

Synchronization:

The completion of the function invocation happens-before a successful return from a call to wait(), get(), wait_for() or wait_until() on any std::experimental::future or std::experimental::shared_future instance that references the same associated state as the std::experimental::future object returned from the std::experimental::async call. In the case of a policy of std::launch::async, the completion of the thread on which the function invocation occurs also happens-before the successful return from these calls.

Throws:

std::bad_alloc if the required internal storage cannot be allocated, otherwise std::future_error when the effects cannot be achieved, or any exception thrown during the construction of fff or xyz....

Note:

std::experimental::async uses std::result_of to deduce the return type of the callable object, and thus the type of future to return. If passing a class object to std::experimental::async you must ensure that it works with std::result_of on your platform, which may require defining a result_type member typedef. This can be achieved by wrapping the object in an instance of std::function.

Header

#include <experimental/future>

just::thread Complete C++ Standard Thread Library by Just Software Solutions

`std::async` function template

Header

See Also