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 requirements for a user-provided function object.
17
18
19API
20***
21
22Header
23------
24
25.. code:: cpp
26
27    #include <oneapi/tbb/task_group.h>
28
29Synopsis
30--------
31
32.. code:: cpp
33
34    namespace oneapi {
35        namespace tbb {
36
37           class task_group {
38           public:
39
40               //only the requirements for the return type of function F are changed
41               template<typename F>
42               task_handle defer(F&& f);
43
44               //only the requirements for the return type of function F are changed
45               template<typename F>
46               task_group_status run_and_wait(const F& f);
47
48               //only the requirements for the return type of function F are changed
49               template<typename F>
50               void run(F&& f);
51           };
52
53        } // namespace tbb
54    } // namespace oneapi
55
56
57
58Member Functions
59----------------
60
61.. cpp:function:: template<typename F> task_handle  defer(F&& f)
62
63As an optimization hint, ``F`` might return a ``task_handle``, which task object can be executed next.
64
65.. note::
66   The ``task_handle`` returned by the function must be created using ``*this`` ``task_group``. That is, the one for which the run method is called, otherwise it is undefined behavior.
67
68.. cpp:function:: template<typename F> task_group_status run_and_wait(const F& f)
69
70As an optimization hint, ``F`` might return a ``task_handle``, which task object can be executed next.
71
72.. note::
73   The ``task_handle`` returned by the function must be created using ``*this`` ``task_group``. That is, the one for which the run method is called, otherwise it is undefined behavior.
74
75
76.. cpp:function:: template<typename F> void  run(F&& f)
77
78As an optimization hint, ``F`` might return a ``task_handle``, which task object can be executed next.
79
80.. note::
81   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.
82
83
84.. rubric:: See also
85
86* `oneapi::tbb::task_group specification <https://spec.oneapi.com/versions/latest/elements/oneTBB/source/task_scheduler/task_group/task_group_cls.html>`_
87* `oneapi::tbb::task_group_context specification <https://spec.oneapi.com/versions/latest/elements/oneTBB/source/task_scheduler/scheduling_controls/task_group_context_cls.html>`_
88* `oneapi::tbb::task_group_status specification <https://spec.oneapi.com/versions/latest/elements/oneTBB/source/task_scheduler/task_group/task_group_status_enum.html>`_
89* `oneapi::tbb::task_handle class <https://oneapi-src.github.io/oneAPI-spec/spec/elements/oneTBB/source/task_scheduler/task_group/task_handle.html>`_
90