task_group extensions

Note

To enable these extensions, set the TBB_PREVIEW_TASK_GROUP_EXTENSIONS macro to 1.

Description

oneAPI Threading Building Blocks (oneTBB) implementation extends the tbb::task_group specification with the following members:

  • constructor that takes a custom tbb::task_group_context object as an argument

  • methods to create and run deferred tasks with task_handle

  • requirements for a user-provided function object

API

Synopsis

namespace oneapi {
    namespace tbb {

       class task_group {
       public:
           task_group(task_group_context& context);

           template<typename F>
           task_handle defer(F&& f);

           void run(task_handle&& h);

           task_group_status run_and_wait(task_handle&&);

           //only the requirements for the return type of function F are changed
           template<typename F>
           void run(F&& f);
       };

    } // namespace tbb
} // namespace oneapi

Member Functions

task_group(task_group_context &context)

Constructs an empty task_group, which tasks are associated with the context.

template<typename F>
task_handle defer(F &&f)

Creates a deferred task to compute f() and returns task_handle pointing to it.

The task is not scheduled for execution until explicitly requested. For example, with the task_group::run method. However, the task is still added into the task_group, thus the task_group::wait method waits until the task_handle is either scheduled or destroyed.

The F type must meet the Function Objects requirements described in the [function.objects] section of the ISO C++ Standard.

As an optimization hint, F might return a task_handle, which task object can be executed next.

Note

The task_handle returned by the function must be created with *this task_group. It means, with the one for which run method is called, otherwise it is an undefined behavior.

Returns: task_handle object pointing to task to compute f().

void run(task_handle &&h)

Schedules the task object pointed by the h for execution.

Caution

If h is empty or *this is not the same task_group that h is created with, the behavior is undefined.

task_group_status run_and_wait(task_handle &&h)

Equivalent to {run(std::move(h)); return wait();}.

Returns: The status of task_group.

Caution

If h is empty or *this is not the same task_group that h is created with, the behavior is undefined.

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

As an optimization hint, F might return a task_handle, which task object can be executed next.

Note

The task_handle returned by the function must be created with *this task_group. It means, with the one for which run method is called, otherwise it is an undefined behavior.

See also