Intel® oneAPI Threading Building Blocks Developer Guide and API Reference
task_group
[scheduler.task_group]
A task_group represents the concurrent execution of a group of tasks. You can dynamically add tasks to the group while it is executing. The thread executing task_group::wait() might participate in other tasks that are not related to the particular task_group.
// Defined in header <oneapi/tbb/task_group.h>
namespace oneapi {
namespace tbb {
class task_group {
public:
task_group();
task_group(task_group_context& context);
~task_group();
template<typename Func>
void run(Func&& f);
template<typename Func>
task_handle defer(Func&& f);
void run(task_handle&& h);
template<typename Func>
task_group_status run_and_wait(const Func& f);
task_group_status run_and_wait(task_handle&& h);
task_group_status wait();
void cancel();
// Preview feature: Waiting an Individual Task
task_group_status wait_for_task(task_completion_handle& ch);
task_group_status run_and_wait_for_task(task_handle&& h);
task_group_status get_status_of(task_completion_handle& ch);
// Preview feature: Dynamic Dependencies
static void set_task_order(task_handle& pred, task_handle& succ);
static void set_task_order(task_completion_handle& pred, task_handle& succ);
static void transfer_this_task_completion_to(task_handle& h);
};
bool is_current_task_group_canceling();
} // namespace tbb
} // namespace oneapiMember functions
task_group()
Constructs an empty task_group.
task_group(task_group_context&context)
Constructs an empty task_group. All tasks added into the task_group are associated with the context.
~task_group()
Destroys the task_group.
Requires: Method wait must be called before destroying a task_group, otherwise, the destructor throws an exception.
template<typenameF>task_handledefer(F&&f)
Creates a deferred task to compute f() and returns task_handle pointing to it.
The task is not scheduled for the execution until it is 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.
Returns:task_handle object pointing to a task to compute f().
template<typenameFunc>voidrun(Func&&f)
Adds a task to compute f() and returns immediately. The Func type must meet the Function Objects requirements described in the [function.objects] section of the ISO C++ standard.
voidrun(task_handle&&h)
Schedules the task object pointed by the h for the execution.
- The failure to satisfy the following conditions leads to undefined behavior:
-
- h is not empty.
*this is the same task_group that h is created with.
template<typenameFunc>task_group_statusrun_and_wait(constFunc&f)
Equivalent to {run(f); return wait();}. The Func type must meet the Function Objects requirements described in the [function.objects] section of the ISO C++ standard.
Returns: The status of task_group. See task_group_status.
task_group_statuswait()
Waits for all tasks in the group to complete or be cancelled.
Returns: The status of task_group. See task_group_status.
voidcancel()
Cancels all tasks in this task_group.
Non-member functions
boolis_current_task_group_canceling()
Returns true if an innermost task_group executing on this thread is cancelling its tasks.
Preview Features
The following preview features extend the task_group API:
Task Bypass Support - allows returning a task_handle from a task body as a hint on which task should be executed next.
Dynamic Dependencies - allows setting execution dependencies between tasks in task_group.
Waiting for Individual Tasks - allows waiting for an individual task to complete in task_group.