Class task_region

Class task_region_handle

hpx::parallel::v2::task_region_handle

Synopsis

// In header: <hpx/parallel/task_region.hpp>


class task_region_handle {
public:

  // public member functions
  template<typename F> void run(F &&);
  void wait();
};

Description

The class task_region_handle defines an interface for forking and joining parallel tasks. The \a task_region and \a task_region_final function templates create an object of type task_region_handle and pass a reference to that object to a user-provided callable object. An object of class \a task_region_handle cannot be constructed, destroyed, copied, or moved except by the implementation of the task region library. Taking the address of a task_region_handle object via operator& or addressof is ill formed. The result of obtaining its address by any other means is unspecified. A \a task_region_handle is active if it was created by the nearest enclosing task region, where "task region" refers to an invocation of task_region or task_region_final 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_region_handle passed to (or captured by) such code is not active within that code. Performing any operation on a task_region_handle that is not active results in undefined behavior. The \a task_region_handle 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 \a task_region_handle from the surrounding block.) @code Example: task_region([&](auto& tr) { tr.run([&] { tr.run([] { f(); }); // Error: tr is not active task_region([&](auto& tr) { // Nested task region tr.run(f); // OK: inner tr is active /// ... }); }); /// ... });

`task_region_handle` public member functions

template<typename F> void run(F && f);

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_region_handle or completion of the nearest enclosing task region (i.e., the task_region or task_region_final that created this task_region_handle).

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

Precondition: this shall be the active task_region_handle.

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:

\a task_canceled_exception, as described in Exception Handling.

```
void wait();
```
Blocks until the tasks spawned using this task_region_handle have finished. Precondition: this shall be the active task_region_handle. 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. \note The call to \a wait is sequenced before the continuation as if \a wait returns on the same thread. \throws \a task_canceled_exception, as described in Exception Handling. @code Example: task_region([&](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] });