1.. _task_group_extensions:
2
3task_group extensions
4=====================
5
6.. note::
7    To enable these extensions, set the ``TBB_PREVIEW_TASK_GROUP_EXTENSIONS`` macro to 1.
8
9.. contents::
10    :local:
11    :depth: 1
12
13Description
14***********
15
16|full_name| implementation extends the `tbb::task_group specification <https://spec.oneapi.com/versions/latest/elements/oneTBB/source/task_scheduler/task_group/task_group_cls.html>`_ with the following members:
17
18  - constructor that takes a custom ``tbb::task_group_context`` object as an argument
19  - methods to create and run deferred tasks with ``task_handle``
20  - requirements for a user-provided function object
21
22
23API
24***
25
26Header
27------
28
29.. code:: cpp
30
31    #include <oneapi/tbb/task_group.h>
32
33Synopsis
34--------
35
36.. code:: cpp
37
38    namespace oneapi {
39        namespace tbb {
40
41           class task_group {
42           public:
43               task_group(task_group_context& context);
44
45               template<typename F>
46               task_handle defer(F&& f);
47
48               void run(task_handle&& h);
49
50               task_group_status run_and_wait(task_handle&&);
51
52               //only the requirements for the return type of function F are changed
53               template<typename F>
54               void run(F&& f);
55           };
56
57        } // namespace tbb
58    } // namespace oneapi
59
60
61
62Member Functions
63----------------
64
65.. cpp:function:: task_group(task_group_context& context)
66
67Constructs an empty ``task_group``, which tasks are associated with the ``context``.
68
69
70.. cpp:function:: template<typename F> task_handle  defer(F&& f)
71
72Creates a deferred task to compute ``f()`` and returns ``task_handle`` pointing to it.
73
74The task is not scheduled for execution until explicitly requested. For example, with the ``task_group::run`` method.
75However, 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.
76
77The ``F`` type must meet the `Function Objects` requirements described in the [function.objects] section of the ISO C++ Standard.
78
79As an optimization hint, ``F`` might return a ``task_handle``, which task object can be executed next.
80
81.. note::
82   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.
83
84**Returns:** ``task_handle`` object pointing to task to compute ``f()``.
85
86
87.. cpp:function:: void run(task_handle&& h)
88
89Schedules the task object pointed by the ``h`` for execution.
90
91.. caution:: If ``h`` is empty or ``*this`` is not the same ``task_group`` that ``h`` is created with, the behavior is undefined.
92
93
94.. cpp:function:: task_group_status run_and_wait(task_handle&& h)
95
96Equivalent to ``{run(std::move(h)); return wait();}``.
97
98**Returns**: The status of ``task_group``.
99
100.. caution::
101   If ``h`` is empty or ``*this`` is not the same ``task_group`` that ``h`` is created with, the behavior is undefined.
102
103
104.. cpp:function:: template<typename F> void  run(F&& f)
105
106As an optimization hint, ``F`` might return a ``task_handle``, which task object can be executed next.
107
108.. note::
109   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.
110
111
112.. rubric:: See also
113
114* `oneapi::tbb::task_group specification <https://spec.oneapi.com/versions/latest/elements/oneTBB/source/task_scheduler/task_group/task_group_cls.html>`_
115* `oneapi::tbb::task_group_context specification <https://spec.oneapi.com/versions/latest/elements/oneTBB/source/task_scheduler/scheduling_controls/task_group_context_cls.html>`_
116* `oneapi::tbb::task_group_status specification <https://spec.oneapi.com/versions/latest/elements/oneTBB/source/task_scheduler/task_group/task_group_status_enum.html>`_
117* :doc:`oneapi::tbb::task_handle class <task_group_extensions/task_handle>`
118