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_contextobject as an argumentmethods to create and run deferred tasks with
task_handlerequirements for a user-provided function object
API¶
Header¶
#include <oneapi/tbb/task_group.h>
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.
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