task_block.hpp#

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

namespace hpx

namespace parallel

Functions

template<typename ExPolicy, typename F> hpx::future<void> define_task_block(ExPolicy &&policy, F &&f)#

Constructs a task_block, tr, using the given execution policy policy,and invokes the expression f(tr) on the user-provided object, f.

Postcondition: All tasks spawned from f have finished execution. A call to define_task_block may return on a different thread than that on which it was called.

Note

It is expected (but not mandated) that f will (directly or indirectly) call tr.run(callable_object).

Template Parameters

ExPolicy – The type of the execution policy to use (deduced). It describes the manner in which the execution of the task block may be parallelized.
F – The type of the user defined function to invoke inside the define_task_block (deduced). F shall be MoveConstructible.

Parameters

policy – The execution policy to use for the scheduling of the iterations.
f – The user defined function to invoke inside the task block. Given an lvalue tr of type task_block, the expression, (void)f(tr), shall be well-formed.

Throws

An – exception_list, as specified in Exception Handling.

template<typename ExPolicy, typename F> void define_task_block(ExPolicy &&policy, F &&f)#

template<typename F> void define_task_block(F &&f)#

Constructs a task_block, tr, and invokes the expression f(tr) on the user-provided object, f. This version uses parallel_policy for task scheduling.

Postcondition: All tasks spawned from f have finished execution. A call to define_task_block may return on a different thread than that on which it was called.

Note

It is expected (but not mandated) that f will (directly or indirectly) call tr.run(callable_object).

Template Parameters: F – The type of the user defined function to invoke inside the define_task_block (deduced). F shall be MoveConstructible.
Parameters: f – The user defined function to invoke inside the task block. Given an lvalue tr of type task_block, the expression, (void)f(tr), shall be well-formed.
Throws: An – exception_list, as specified in Exception Handling.

template<typename ExPolicy, typename F> util::detail::algorithm_result<ExPolicy>::type define_task_block_restore_thread(ExPolicy &&policy, F &&f)#

Constructs a task_block, tr, and invokes the expression f(tr) on the user-provided object, f.

Postcondition: All tasks spawned from f have finished execution. A call to define_task_block_restore_thread always returns on the same thread as that on which it was called.

Note

It is expected (but not mandated) that f will (directly or indirectly) call tr.run(callable_object).

Template Parameters

ExPolicy – The type of the execution policy to use (deduced). It describes the manner in which the execution of the task block may be parallelized.
F – The type of the user defined function to invoke inside the define_task_block (deduced). F shall be MoveConstructible.

Parameters

policy – The execution policy to use for the scheduling of the iterations.
f – The user defined function to invoke inside the define_task_block. Given an lvalue tr of type task_block, the expression, (void)f(tr), shall be well-formed.

Throws

An – exception_list, as specified in Exception Handling.

template<typename F> void define_task_block_restore_thread(F &&f)#

Constructs a task_block, tr, and invokes the expression f(tr) on the user-provided object, f. This version uses parallel_policy for task scheduling.

Postcondition: All tasks spawned from f have finished execution. A call to define_task_block_restore_thread always returns on the same thread as that on which it was called.

Note

It is expected (but not mandated) that f will (directly or indirectly) call tr.run(callable_object).

Template Parameters: F – The type of the user defined function to invoke inside the define_task_block (deduced). F shall be MoveConstructible.
Parameters: f – The user defined function to invoke inside the define_task_block. Given an lvalue tr of type task_block, the expression, (void)f(tr), shall be well-formed.
Throws: An – exception_list, as specified in Exception Handling.

namespace v2

template<typename ExPolicy = hpx::execution::parallel_policy> class task_block#

#include <task_block.hpp>

The class task_block defines an interface for forking and joining parallel tasks. The define_task_block and define_task_block_restore_thread function templates create an object of type task_block and pass a reference to that object to a user-provided callable object.

An object of class task_block cannot be constructed, destroyed, copied, or moved except by the implementation of the task region library. Taking the address of a task_block object via operator& or addressof is ill formed. The result of obtaining its address by any other means is unspecified.

A task_block

is active if it was created by the nearest enclosing task block, where “task block” refers to an invocation of define_task_block or define_task_block_restore_thread and “nearest

enclosing” means the most recent invocation that has not yet completed. Code designated for execution in another thread by means other than the facilities in this section (e.g., using thread or async) are not enclosed in the task region and a

task_block passed to (or captured by) such code is not active within that code. Performing any operation on a task_block that is not active results in undefined behavior.

The task_block that is active before a specific call to the run member function is not active within the asynchronous function that invoked run. (The invoked function should not, therefore, capture the task_block from the surrounding block.)

Example:
    define_task_block([&](auto& tr) {
        tr.run([&] {
            tr.run([] { f(); });                // Error: tr is not active
            define_task_block([&](auto& tr) {   // Nested task block
                tr.run(f);                      // OK: inner tr is active
                /// ...
            });
        });
        /// ...
    });

Template Parameters: ExPolicy – The execution policy an instance of a task_block was created with. This defaults to parallel_policy.

Public Types

using execution_policy = ExPolicy #: Refers to the type of the execution policy used to create the task_block.

Public Functions

inline execution_policy const &get_execution_policy() const#: Return the execution policy instance used to create this task_block

template<typename F, typename ...Ts> inline void run(F &&f, Ts&&... ts)#

Causes the expression f() to be invoked asynchronously. The invocation of f is permitted to run on an unspecified thread in an unordered fashion relative to the sequence of operations following the call to run(f) (the continuation), or indeterminately sequenced within the same thread as the continuation.

The call to run synchronizes with the invocation of f. The completion of f() synchronizes with the next invocation of wait on the same task_block or completion of the nearest enclosing task block (i.e., the define_task_block or define_task_block_restore_thread that created this task block).

Requires: F shall be MoveConstructible. The expression, (void)f(), shall be well-formed.

Precondition: this shall be the active task_block.

Postconditions: A call to run may return on a different thread than that on which it was called.

Note

The call to run is sequenced before the continuation as if run returns on the same thread. The invocation of the user-supplied callable object f may be immediate or may be delayed until compute resources are available. run might or might not return before invocation of f completes.

Throws: This – function may throw task_canceled_exception, as described in Exception Handling.

template<typename Executor, typename F, typename ...Ts> inline void run(Executor &&exec, F &&f, Ts&&... ts)#

Causes the expression f() to be invoked asynchronously using the given executor. The invocation of f is permitted to run on an unspecified thread associated with the given executor and in an unordered fashion relative to the sequence of operations following the call to run(exec, f) (the continuation), or indeterminately sequenced within the same thread as the continuation.

Requires: Executor shall be a type modeling the Executor concept. F shall be MoveConstructible. The expression, (void)f(), shall be well-formed.

Precondition: this shall be the active task_block.

Postconditions: A call to run may return on a different thread than that on which it was called.

Note

Throws: This – function may throw task_canceled_exception, as described in Exception Handling. The function will also throw a exception_list holding all exceptions that were caught while executing the tasks.

inline void wait()#

Blocks until the tasks spawned using this task_block have finished.

Precondition: this shall be the active task_block.

Postcondition: All tasks spawned by the nearest enclosing task region have finished. A call to wait may return on a different thread than that on which it was called.

Example:
    define_task_block([&](auto& tr) {
        tr.run([&]{ process(a, w, x); }); // Process a[w] through a[x]
        if (y < x) tr.wait();   // Wait if overlap between [w, x) and [y, z)
        process(a, y, z);       // Process a[y] through a[z]
    });

Note

The call to wait is sequenced before the continuation as if wait returns on the same thread.

Throws: This – function may throw task_canceled_exception, as described in Exception Handling. The function will also throw a exception_list holding all exceptions that were caught while executing the tasks.

inline ExPolicy &policy()#

Returns a reference to the execution policy used to construct this object.

Precondition: this shall be the active task_block.

inline ExPolicy const &policy() const#

Returns a reference to the execution policy used to construct this object.

Precondition: this shall be the active task_block.

Private Members

hpx::execution::experimental::task_group tasks_#

threads::thread_id_type id_#

ExPolicy policy_#

class task_canceled_exception : public exception #

#include <task_block.hpp>

The class task_canceled_exception defines the type of objects thrown by task_block::run or task_block::wait if they detect that an exception is pending within the current parallel region.

Public Functions

inline task_canceled_exception() noexcept#