<future> functions

async
future_category
make_error_code
make_error_condition
swap|

async

Represents an asynchronous provider.

template <class Fn, class... ArgTypes>
future<typename result_of<Fn(ArgTypes...)>::type>
    async(Fn&& fn, ArgTypes&&... args);

template <class Fn, class... ArgTypes>
future<typename result_of<Fn(ArgTypes...)>::type>
    async(launch policy, Fn&& fn, ArgTypes&&... args);

Parameters

policy
A launch value.

Remarks

Definitions of abbreviations:

Abbreviation Description
dfn The result of calling decay_copy(forward<Fn>(fn)).
dargs The results of the calls decay_copy(forward<ArgsTypes>(args...)).
Ty The type result_of<Fn(ArgTypes...)>::type.

The first template function returns async(launch::any, fn, args...).

The second function returns a future<Ty> object whose associated asynchronous state holds a result together with the values of dfn and dargs and a thread object to manage a separate thread of execution.

Unless decay<Fn>::type is a type other than launch, the second function doesn't participate in overload resolution.

The C++ standard states that if policy is launch::async, the function creates a new thread. However the Microsoft implementation is currently non-conforming. It obtains its threads from the Windows ThreadPool, which in some cases may provide a recycled thread rather than a new one. This means that the launch::async policy is implemented as launch::async|launch::deferred. Another implication of the ThreadPool-based implementation is that there's no guarantee that thread-local variables will be destroyed when the thread completes. If the thread is recycled and provided to a new call to async, the old variables will still exist. We recommend that you don't use thread-local variables with async.

If policy is launch::deferred, the function marks its associated asynchronous state as holding a deferred function and returns. The first call to any non-timed function that waits for the associated asynchronous state to be ready in effect calls the deferred function by evaluating INVOKE(dfn, dargs..., Ty).

In all cases, the associated asynchronous state of the future object isn't set to ready until the evaluation of INVOKE(dfn, dargs..., Ty) completes, either by throwing an exception or by returning normally. The result of the associated asynchronous state is an exception if one was thrown, or any value that's returned by the evaluation.

Note

For a future—or the last shared_future—that's attached to a task started with std::async, the destructor blocks if the task has not completed; that is, it blocks if this thread did not yet call .get() or .wait() and the task is still running. If a future obtained from std::async is moved outside the local scope, other code that uses it must be aware that its destructor may block for the shared state to become ready.

The pseudo-function INVOKE is defined in <functional>.

Microsoft Specific

When the passed function is executed asynchronously, it's executed on Windows Thread Pool; see Thread Pools. The number of concurrent threads is limited to the thread pool default (currently 500). The number of threads concurrently executing on hardware is currently limited by the number of logical processor in the process's processor group, so it's effectively limited to 64; see Processor Groups.

future_category

Returns a reference to the error_category object that characterizes errors that are associated with future objects.

const error_category& future_category() noexcept;

make_error_code

Creates an error_code together with the error_category object that characterizes future errors.

inline error_code make_error_code(future_errc Errno) noexcept;

Parameters

Errno
A future_errc value that identifies the reported error.

Return Value

error_code(static_cast<int>(Errno), future_category());

make_error_condition

Creates an error_condition together with the error_category object that characterizes future errors.

inline error_condition make_error_condition(future_errc Errno) noexcept;

Parameters

Errno
A future_errc value that identifies the reported error.

Return Value

error_condition(static_cast<int>(Errno), future_category());

swap

Exchanges the associated asynchronous state of one promise object with that of another.

template <class Ty>
void swap(promise<Ty>& Left, promise<Ty>& Right) noexcept;

template <class Ty, class... ArgTypes>
void swap(packaged_task<Ty(ArgTypes...)>& Left, packaged_task<Ty(ArgTypes...)>& Right) noexcept;

Parameters

Left
The left promise object.

Right
The right promise object.

See also

<future>