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