execution.hpp#

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

namespace hpx

namespace execution

struct parallel_execution_tag#: #include <execution.hpp>

Function invocations executed by a group of parallel execution agents execute in unordered fashion. Any such invocations executing in the same thread are indeterminately sequenced with respect to each other.

Note

parallel_execution_tag is weaker than sequenced_execution_tag.

struct sequenced_execution_tag#: #include <execution.hpp>

Function invocations executed by a group of sequential execution agents execute in sequential order.

struct unsequenced_execution_tag#: #include <execution.hpp>

Function invocations executed by a group of vector execution agents are permitted to execute in unordered fashion when executed in different threads, and un-sequenced with respect to one another when executed in the same thread.

Note

unsequenced_execution_tag is weaker than parallel_execution_tag.

namespace parallel

namespace execution

Variables

hpx::parallel::execution::sync_execute_t sync_execute#

hpx::parallel::execution::async_execute_t async_execute#

hpx::parallel::execution::then_execute_t then_execute#

hpx::parallel::execution::post_t post#

hpx::parallel::execution::bulk_sync_execute_t bulk_sync_execute#

hpx::parallel::execution::bulk_async_execute_t bulk_async_execute#

hpx::parallel::execution::bulk_then_execute_t bulk_then_execute#

struct async_execute_t : public hpx::functional::detail::tag_fallback<async_execute_t>#

#include <execution.hpp>

Customization point for asynchronous execution agent creation.

This asynchronously creates a single function invocation f() using the associated executor.

Note

Executors have to implement only async_execute(). All other functions will be emulated by this or other customization points in terms of this single basic primitive. However, some executors will naturally specialize all operations for maximum efficiency.

Note

This is valid for one way executors (calls make_ready_future(exec.sync_execute(f, ts…) if it exists) and for two way executors (calls exec.async_execute(f, ts…) if it exists).

Param exec: [in] The executor object to use for scheduling of the function f.
Param f: [in] The function which will be scheduled using the given executor.
Param ts: [in] Additional arguments to use to invoke f.
Return: f(ts…)’s result through a future

Private Functions

template<typename Executor, typename F, typename ...Ts> inline decltype(auto) friend tag_fallback_invoke(async_execute_t, Executor &&exec, F &&f, Ts&&... ts)#

struct bulk_async_execute_t : public hpx::functional::detail::tag_fallback<bulk_async_execute_t>#

#include <execution.hpp>

Bulk form of asynchronous execution agent creation.

This asynchronously creates a group of function invocations f(i) whose ordering is given by the execution_category associated with the executor.

Here i takes on all values in the index space implied by shape. All exceptions thrown by invocations of f(i) are reported in a manner consistent with parallel algorithm execution through the returned future.

Note

This is deliberately different from the bulk_async_execute customization points specified in P0443.The bulk_async_execute customization point defined here is more generic and is used as the workhorse for implementing the specified APIs.

Note

This calls exec.bulk_async_execute(f, shape, ts…) if it exists; otherwise it executes async_execute(f, shape, ts…) as often as needed.

Param exec: [in] The executor object to use for scheduling of the function f.
Param f: [in] The function which will be scheduled using the given executor.
Param shape: [in] The shape objects which defines the iteration boundaries for the arguments to be passed to f.
Param ts: [in] Additional arguments to use to invoke f.
Return: The return type of executor_type::bulk_async_execute if defined by executor_type. Otherwise a vector of futures holding the returned values of each invocation of f.

Private Functions

template<typename Executor, typename F, typename Shape, typename ...Ts> inline decltype(auto) friend tag_fallback_invoke(bulk_async_execute_t, Executor &&exec, F &&f, Shape const &shape, Ts&&... ts)#

template<typename Executor, typename F, typename Shape, typename ...Ts> inline decltype(auto) friend tag_fallback_invoke(bulk_async_execute_t, Executor &&exec, F &&f, Shape const &shape, Ts&&... ts)

struct bulk_sync_execute_t : public hpx::functional::detail::tag_fallback<bulk_sync_execute_t>#

#include <execution.hpp>

Bulk form of synchronous execution agent creation.

This synchronously creates a group of function invocations f(i) whose ordering is given by the execution_category associated with the executor. The function synchronizes the execution of all scheduled functions with the caller.

Note

This is deliberately different from the bulk_sync_execute customization points specified in P0443.The bulk_sync_execute customization point defined here is more generic and is used as the workhorse for implementing the specified APIs.

Note

This calls exec.bulk_sync_execute(f, shape, ts…) if it exists; otherwise it executes sync_execute(f, shape, ts…) as often as needed.

Param exec: [in] The executor object to use for scheduling of the function f.
Param f: [in] The function which will be scheduled using the given executor.
Param shape: [in] The shape objects which defines the iteration boundaries for the arguments to be passed to f.
Param ts: [in] Additional arguments to use to invoke f.
Return: The return type of executor_type::bulk_sync_execute if defined by executor_type. Otherwise a vector holding the returned values of each invocation of f except when f returns void, which case void is returned.

Private Functions

template<typename Executor, typename F, typename Shape, typename ...Ts> inline decltype(auto) friend tag_fallback_invoke(bulk_sync_execute_t, Executor &&exec, F &&f, Shape const &shape, Ts&&... ts)#

template<typename Executor, typename F, typename Shape, typename ...Ts> inline decltype(auto) friend tag_fallback_invoke(bulk_sync_execute_t, Executor &&exec, F &&f, Shape const &shape, Ts&&... ts)

struct bulk_then_execute_t : public hpx::functional::detail::tag_fallback<bulk_then_execute_t>#

#include <execution.hpp>

Bulk form of execution agent creation depending on a given future.

This creates a group of function invocations f(i) whose ordering is given by the execution_category associated with the executor.

Note

This is deliberately different from the then_sync_execute customization points specified in P0443.The bulk_then_execute customization point defined here is more generic and is used as the workhorse for implementing the specified APIs.

Note

This calls exec.bulk_then_execute(f, shape, pred, ts…) if it exists; otherwise it executes sync_execute(f, shape, pred.share(), ts…) (if this executor is also an OneWayExecutor), or async_execute(f, shape, pred.share(), ts…) (if this executor is also a TwoWayExecutor) - as often as needed.

Param exec: [in] The executor object to use for scheduling of the function f.
Param f: [in] The function which will be scheduled using the given executor.
Param shape: [in] The shape objects which defines the iteration boundaries for the arguments to be passed to f.
Param predecessor: [in] The future object the execution of the given function depends on.
Param ts: [in] Additional arguments to use to invoke f.
Return: The return type of executor_type::bulk_then_execute if defined by executor_type. Otherwise a vector holding the returned values of each invocation of f.

Private Functions

template<typename Executor, typename F, typename Shape, typename Future, typename ...Ts> inline decltype(auto) friend tag_fallback_invoke(bulk_then_execute_t, Executor &&exec, F &&f, Shape const &shape, Future &&predecessor, Ts&&... ts)#

template<typename Executor, typename F, typename Shape, typename Future, typename ...Ts> inline decltype(auto) friend tag_fallback_invoke(bulk_then_execute_t, Executor &&exec, F &&f, Shape const &shape, Future &&predecessor, Ts&&... ts)

struct post_t : public hpx::functional::detail::tag_fallback<post_t>#

#include <execution.hpp>

Customization point for asynchronous fire & forget execution agent creation.

This asynchronously (fire & forget) creates a single function invocation f() using the associated executor.

Note

This is valid for two way executors (calls exec.post(f, ts…), if available, otherwise it calls exec.async_execute(f, ts…) while discarding the returned future), and for non-blocking two way executors (calls exec.post(f, ts…) if it exists).

Param exec: [in] The executor object to use for scheduling of the function f.
Param f: [in] The function which will be scheduled using the given executor.
Param ts: [in] Additional arguments to use to invoke f.

Private Functions

template<typename Executor, typename F, typename ...Ts> inline decltype(auto) friend tag_fallback_invoke(post_t, Executor &&exec, F &&f, Ts&&... ts)#

struct sync_execute_t : public hpx::functional::detail::tag_fallback<sync_execute_t>#

#include <execution.hpp>

Customization point for synchronous execution agent creation.

This synchronously creates a single function invocation f() using the associated executor. The execution of the supplied function synchronizes with the caller

Note

It will call tag_invoke(sync_execute_t, exec, f, ts…) if it exists. For two-way executors it will invoke asynch_execute_t and wait for the task’s completion before returning.

Param exec: [in] The executor object to use for scheduling of the function f.
Param f: [in] The function which will be scheduled using the given executor.
Param ts: [in] Additional arguments to use to invoke f.
Return: f(ts…)’s result

Private Functions

template<typename Executor, typename F, typename ...Ts> inline decltype(auto) friend tag_fallback_invoke(sync_execute_t, Executor &&exec, F &&f, Ts&&... ts)#

struct then_execute_t : public hpx::functional::detail::tag_fallback<then_execute_t>#

#include <execution.hpp>

Customization point for execution agent creation depending on a given future.

This creates a single function invocation f() using the associated executor after the given future object has become ready.

Note

This is valid for two way executors (calls exec.then_execute(f, predecessor, ts…) if it exists) and for one way executors (calls predecessor.then(bind(f, ts…))).

Param exec: [in] The executor object to use for scheduling of the function f.
Param f: [in] The function which will be scheduled using the given executor.
Param predecessor: [in] The future object the execution of the given function depends on.
Param ts: [in] Additional arguments to use to invoke f.
Return: f(ts…)’s result through a future

Private Functions

template<typename Executor, typename F, typename Future, typename ...Ts> inline decltype(auto) friend tag_fallback_invoke(then_execute_t, Executor &&exec, F &&f, Future &&predecessor, Ts&&... ts)#