hpx::async#

Defined in header hpx/future.hpp.

See Public API for a list of names and headers that are part of the public HPX API.

See also

hpx::async (distributed)

template<typename Action, typename F, typename ...Ts>
auto hpx::async(F &&f, Ts&&... ts) -> decltype(detail::async_action_dispatch<Action, std::decay_t<F>>::call(HPX_FORWARD(F, f), HPX_FORWARD(Ts, ts)...))#

The function template async runs the function f asynchronously (potentially in a separate thread which might be a part of a thread pool) and returns a hpx::future that will eventually hold the result of that function call. If no policy is defined, async behaves as if it is called with policy being hpx::launch::async | hpx::launch::deferred. Otherwise, it calls a function f with arguments ts according to a specific launch policy.

  • If the async flag is set (i.e. (policy & hpx::launch::async) != 0), then async executes the callable object f on a new thread of execution (with all thread-locals initialized) as if spawned by hpx::thread(std::forward<F>(f), std::forward<Ts>(ts)…), except that if the function f returns a value or throws an exception, it is stored in the shared state accessible through the hpx::future that async returns to the caller.

  • If the deferred flag is set (i.e. (policy & hpx::launch::deferred) != 0), then async converts f and ts… the same way as by hpx::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 hpx::future that async returned to the caller will cause the copy of f to be invoked (as a rvalue) with the copies of ts… (also passed as rvalues) in the current thread (which does not have to be the thread that originally called hpx::async). The result or exception is placed in the shared state associated with the future and only then it is made ready. All further accesses to the same hpx::future will return the result immediately.

  • If neither hpx::launch::async nor hpx::launch::deferred, nor any implementation-defined policy flag is set in policy, the behavior is undefined.

If more than one flag is set, it is implementation-defined which policy is selected. For the default (both the hpx::launch::async and hpx::launch::deferred flags are set in policy), standard recommends (but doesn’t require) utilizing available concurrency, and deferring any additional tasks.

In any case, the call to hpx::async synchronizes-with (as defined in std::memory_order) the call to f, and the completion of f is sequenced-before making the shared state ready. If the async policy is chosen, the associated thread completion synchronizes-with the successful return from the first function that is waiting on the shared state, or with the return of the last function that releases the shared state, whichever comes first. If std::decay<Function>::type or each type in std::decay<Ts>::type is not constructible from its corresponding argument, the program is ill-formed.

Parameters

  • f – Callable object to call

  • ts – parameters to pass to f

Returns

hpx::future referring to the shared state created by this call to hpx::async.

template<typename Action, typename F, typename ...Ts>
auto hpx::async(F &&f, Ts&&... ts) -> decltype(detail::async_action_dispatch<Action, std::decay_t<F>>::call(HPX_FORWARD(F, f), HPX_FORWARD(Ts, ts)...))

The function template async runs the function f asynchronously (potentially in a separate thread which might be a part of a thread pool) and returns a hpx::future that will eventually hold the result of that function call. If no policy is defined, async behaves as if it is called with policy being hpx::launch::async | hpx::launch::deferred. Otherwise, it calls a function f with arguments ts according to a specific launch policy.

  • If the async flag is set (i.e. (policy & hpx::launch::async) != 0), then async executes the callable object f on a new thread of execution (with all thread-locals initialized) as if spawned by hpx::thread(std::forward<F>(f), std::forward<Ts>(ts)…), except that if the function f returns a value or throws an exception, it is stored in the shared state accessible through the hpx::future that async returns to the caller.

  • If the deferred flag is set (i.e. (policy & hpx::launch::deferred) != 0), then async converts f and ts… the same way as by hpx::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 hpx::future that async returned to the caller will cause the copy of f to be invoked (as a rvalue) with the copies of ts… (also passed as rvalues) in the current thread (which does not have to be the thread that originally called hpx::async). The result or exception is placed in the shared state associated with the future and only then it is made ready. All further accesses to the same hpx::future will return the result immediately.

  • If neither hpx::launch::async nor hpx::launch::deferred, nor any implementation-defined policy flag is set in policy, the behavior is undefined.

If more than one flag is set, it is implementation-defined which policy is selected. For the default (both the hpx::launch::async and hpx::launch::deferred flags are set in policy), standard recommends (but doesn’t require) utilizing available concurrency, and deferring any additional tasks.

In any case, the call to hpx::async synchronizes-with (as defined in std::memory_order) the call to f, and the completion of f is sequenced-before making the shared state ready. If the async policy is chosen, the associated thread completion synchronizes-with the successful return from the first function that is waiting on the shared state, or with the return of the last function that releases the shared state, whichever comes first. If std::decay<Function>::type or each type in std::decay<Ts>::type is not constructible from its corresponding argument, the program is ill-formed.

Parameters

  • f – Callable object to call

  • ts – parameters to pass to f

Returns

hpx::future referring to the shared state created by this call to hpx::async.

Warning

doxygenfunction: Unable to resolve function “hpx::async” with arguments (Executor&&, hpx::sycl::experimental::sycl_executor::queue_function_ptr_t<Ts…>&&, Ts&&…) in doxygen xml output for project “hpx” from directory: ../hpx_autodoc. Potential matches: 

- template<typename Action, typename F, typename ...Ts> auto async(F &&f, Ts&&... ts) -> decltype(detail::async_action_dispatch<Action, std::decay_t<F>>::call(HPX_FORWARD(F, f), HPX_FORWARD(Ts, ts)...))
- template<typename Action, typename Target, typename ...Ts> auto async(Action &&action, Target &&target, Ts&&... ts)
- template<typename Executor, typename ...Ts> decltype(auto) async(Executor &&exec, hpx::sycl::experimental::sycl_executor::queue_function_ptr_t<Ts...> &&f, Ts&&... ts)
- template<typename F, typename ...Ts> decltype(auto) async(F &&f, Ts&&... ts)
template<typename Action, typename Target, typename ...Ts>
auto hpx::async(Action &&action, Target &&target, Ts&&... ts)#

The distributed implementation of hpx::async can be used by giving an action instance as argument instead of a function, and also by providing another argument with the locality ID or the target ID. The action executes asynchronously.

Template Parameters

  • Action – The type of action instance

  • Target – The type of target where the action should be executed

  • Ts – The type of any additional arguments

Parameters

  • action – The action instance to be executed

  • target – The target where the action should be executed

  • ts – Additional arguments

Returns

hpx::future referring to the shared state created by this call to hpx::async