From 4890ea20967665645512830842186ab5f11a0e8f Mon Sep 17 00:00:00 2001 From: Anton Potapov Date: Wed, 18 Aug 2021 14:08:24 +0300 Subject: [PATCH 01/12] [oneTBB] task_handle related extensions --- .../elements/oneTBB/source/task_scheduler.rst | 1 + .../task_arena/task_arena_cls.rst | 10 +++ .../task_arena/this_task_arena_ns.rst | 20 +++++ .../task_group/task_group_cls.rst | 38 +++++++++ .../task_scheduler/task_group/task_handle.rst | 80 +++++++++++++++++++ 5 files changed, 149 insertions(+) create mode 100644 source/elements/oneTBB/source/task_scheduler/task_group/task_handle.rst diff --git a/source/elements/oneTBB/source/task_scheduler.rst b/source/elements/oneTBB/source/task_scheduler.rst index a4bd41addf..01491cfb77 100644 --- a/source/elements/oneTBB/source/task_scheduler.rst +++ b/source/elements/oneTBB/source/task_scheduler.rst @@ -46,6 +46,7 @@ Task Group task_scheduler/task_group/task_group_cls.rst task_scheduler/task_group/task_group_status_enum.rst + task_scheduler/task_group/task_handle.rst Task Arena ---------- diff --git a/source/elements/oneTBB/source/task_scheduler/task_arena/task_arena_cls.rst b/source/elements/oneTBB/source/task_scheduler/task_arena/task_arena_cls.rst index fda4251a51..c8ad516a6f 100644 --- a/source/elements/oneTBB/source/task_scheduler/task_arena/task_arena_cls.rst +++ b/source/elements/oneTBB/source/task_scheduler/task_arena/task_arena_cls.rst @@ -54,6 +54,8 @@ A class that represents an explicit, user-managed task scheduler arena. template auto execute(F&& f) -> decltype(f()); template void enqueue(F&& f); + + void enqueue(task_handle&& h); }; } // namespace tbb @@ -251,6 +253,14 @@ Member functions Any number of threads outside of the arena can submit work to the arena and be blocked. However, only the maximal number of threads specified for the arena can participate in executing the work. +.. cpp:function:: void enqueue(task_handle&& h) + + Enqueues a task owned by ``h`` into the ``task_arena`` for procession. + + Behavior of this function is identical to generic version (``template void task_arena::enqueue(F&& f)``) except parameter type. + + .. note:: + ``h`` should not be empty to avoid undefined behavior. Example ------- diff --git a/source/elements/oneTBB/source/task_scheduler/task_arena/this_task_arena_ns.rst b/source/elements/oneTBB/source/task_scheduler/task_arena/this_task_arena_ns.rst index c99317bcbe..e103c03da8 100644 --- a/source/elements/oneTBB/source/task_scheduler/task_arena/this_task_arena_ns.rst +++ b/source/elements/oneTBB/source/task_scheduler/task_arena/this_task_arena_ns.rst @@ -21,6 +21,10 @@ with the ``task_arena`` currently used by the calling thread. int current_thread_index(); int max_concurrency(); template auto isolate(F&& f) -> decltype(f()); + + void enqueue(task_handle&& h); + + template void enqueue(F&& f) ; } } @@ -65,3 +69,19 @@ with the ``task_arena`` currently used by the calling thread. The object returned by the functor cannot be a reference. ``std::reference_wrapper`` can be used instead. +.. cpp:function:: template void enqueue(F&& f) + + Enqueues a task into the ``task_arena`` currently used by the calling thread to process the specified functor, then immediately returns. + The ``F`` type must meet the `Function Objects` requirements from the [function.objects] ISO C++ Standard section. + + Behavior of this function is identical to ``template void task_arena::enqueue(F&& f)`` applied to ``task_arena`` + object constructed with ``attach`` parameter. + +.. cpp:function:: void enqueue(task_handle&& h) + + Enqueues a task owned by ``h`` into the ``task_arena`` that is currently used by the calling thread. + + Behavior of this function is identical to generic version (``template void enqueue(F&& f)``) except the parameter type. + + .. note:: + ``h`` should not be empty to avoid undefined behavior. diff --git a/source/elements/oneTBB/source/task_scheduler/task_group/task_group_cls.rst b/source/elements/oneTBB/source/task_scheduler/task_group/task_group_cls.rst index 27b2fe1ab4..911e76b445 100644 --- a/source/elements/oneTBB/source/task_scheduler/task_group/task_group_cls.rst +++ b/source/elements/oneTBB/source/task_scheduler/task_group/task_group_cls.rst @@ -23,6 +23,11 @@ Tasks can be dynamically added to the group while it is executing. template void run( Func&& f ); + + template + task_handle defer(Func&& f); + + void run(task_handle&& h); template task_group_status run_and_wait( const Func& f ); @@ -51,10 +56,43 @@ Member functions **Requires**: Method ``wait`` must be called before destroying a ``task_group``, otherwise, the destructor throws an exception. +.. cpp:function:: template 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 from [function.objects] ISO C++ Standard section. + + 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()``. + .. cpp:function:: template void run( Func&& f ) Adds a task to compute ``f()`` and returns immediately. The ``Func`` type must meet the `Function Objects` requirements from [function.objects] ISO C++ Standard section. + + 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. + +.. cpp:function:: void run(task_handle&& h) + + Schedules the task object pointed by the ``h`` for execution. + + .. note:: + 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. .. cpp:function:: template task_group_status run_and_wait( const Func& f ) diff --git a/source/elements/oneTBB/source/task_scheduler/task_group/task_handle.rst b/source/elements/oneTBB/source/task_scheduler/task_group/task_handle.rst new file mode 100644 index 0000000000..7ce8e30d9b --- /dev/null +++ b/source/elements/oneTBB/source/task_scheduler/task_group/task_handle.rst @@ -0,0 +1,80 @@ +.. SPDX-FileCopyrightText: 2019-2020 Intel Corporation +...................................................... +.. SPDX-License-Identifier: CC-BY-4.0 + +=========== +task_handle +=========== +**[scheduler.task_handle]** + +An instance of ``task_handle`` type owns a deferred task object. + +.. code:: cpp + + namespace tbb { + + class task_handle { + public: + task_handle(); + task_handle(task_handle&& src); + + ~task_handle(); + + task_handle& operator=(task_handle&& src); + + explicit operator bool() const noexcept; + }; + + bool operator==(task_handle const& h, std::nullptr_t) noexcept; + bool operator==(std::nullptr_t, task_handle const& h) noexcept; + + bool operator!=(task_handle const& h, std::nullptr_t) noexcept; + bool operator!=(std::nullptr_t, task_handle const& h) noexcept; + + } // namespace tbb + + +Member Functions +---------------- + +.. cpp:function:: task_handle() + + Creates an empty ``task_handle`` object. + +.. cpp:function:: task_handle(task_handle&& src) + + Constructs ``task_handle`` object with the content of ``src`` using move semantics. ``src`` is left in an empty state. + +.. cpp:function:: ~task_handle() + + Destroys the ``task_handle`` object and associated task if it exists. + +.. cpp:function:: task_handle& operator=(task_handle&& src) + + Replaces the content of ``task_handle`` object with the content of ``src`` using move semantics. ``src`` is left in an empty state. + The previously associated task object, if any, is destroyed before the assignment. + + **Returns:** Reference to ``*this``. + +.. cpp:function:: explicit operator bool() const noexcept + + Checks if ``*this`` has an associated task object. + + **Returns:** ``true`` if ``*this`` is not empty, ``false`` otherwise. + +Non-Member Functions +-------------------- + +.. code:: cpp + + bool operator==(task_handle const& h, std::nullptr_t) noexcept + bool operator==(std::nullptr_t, task_handle const& h) noexcept + + **Returns**: ``true`` if ``h`` is empty, ``false`` otherwise. + +.. code:: cpp + + bool operator!=(task_handle const& h, std::nullptr_t) noexcept + bool operator!=(std::nullptr_t, task_handle const& h) noexcept + + **Returns**: ``true`` if ``h`` is not empty, ``false`` otherwise. \ No newline at end of file From f74a61d5dc1bea1223a3c2bdaba5ea33d13fa643 Mon Sep 17 00:00:00 2001 From: Anton Potapov Date: Thu, 26 Aug 2021 17:48:43 +0300 Subject: [PATCH 02/12] [oneTBB] task_handle related extensions - Fixed wording during code review Co-authored-by: Alexandra --- .../task_scheduler/task_arena/task_arena_cls.rst | 6 +++--- .../task_scheduler/task_arena/this_task_arena_ns.rst | 10 +++++----- .../task_scheduler/task_group/task_group_cls.rst | 12 ++++++------ 3 files changed, 14 insertions(+), 14 deletions(-) diff --git a/source/elements/oneTBB/source/task_scheduler/task_arena/task_arena_cls.rst b/source/elements/oneTBB/source/task_scheduler/task_arena/task_arena_cls.rst index c8ad516a6f..5288e8ebdb 100644 --- a/source/elements/oneTBB/source/task_scheduler/task_arena/task_arena_cls.rst +++ b/source/elements/oneTBB/source/task_scheduler/task_arena/task_arena_cls.rst @@ -255,12 +255,12 @@ Member functions .. cpp:function:: void enqueue(task_handle&& h) - Enqueues a task owned by ``h`` into the ``task_arena`` for procession. + Enqueues a task owned by ``h`` into the ``task_arena`` for processing. - Behavior of this function is identical to generic version (``template void task_arena::enqueue(F&& f)``) except parameter type. + The behavior of this function is identical to the generic version (``template void task_arena::enqueue(F&& f)``), except parameter type. .. note:: - ``h`` should not be empty to avoid undefined behavior. + ``h`` should not be empty to avoid an undefined behavior. Example ------- diff --git a/source/elements/oneTBB/source/task_scheduler/task_arena/this_task_arena_ns.rst b/source/elements/oneTBB/source/task_scheduler/task_arena/this_task_arena_ns.rst index e103c03da8..4cf3ee50c3 100644 --- a/source/elements/oneTBB/source/task_scheduler/task_arena/this_task_arena_ns.rst +++ b/source/elements/oneTBB/source/task_scheduler/task_arena/this_task_arena_ns.rst @@ -71,17 +71,17 @@ with the ``task_arena`` currently used by the calling thread. .. cpp:function:: template void enqueue(F&& f) - Enqueues a task into the ``task_arena`` currently used by the calling thread to process the specified functor, then immediately returns. - The ``F`` type must meet the `Function Objects` requirements from the [function.objects] ISO C++ Standard section. + Enqueues a task into the ``task_arena`` currently used by the calling thread to process the specified functor, then returns immediately. + The ``F`` type must meet the `Function Objects` requirements described in the [function.objects] section of the ISO C++ standard. - Behavior of this function is identical to ``template void task_arena::enqueue(F&& f)`` applied to ``task_arena`` + Behavior of this function is identical to ``template void task_arena::enqueue(F&& f)`` applied to the ``task_arena`` object constructed with ``attach`` parameter. .. cpp:function:: void enqueue(task_handle&& h) Enqueues a task owned by ``h`` into the ``task_arena`` that is currently used by the calling thread. - Behavior of this function is identical to generic version (``template void enqueue(F&& f)``) except the parameter type. + The behavior of this function is identical to the generic version (``template void enqueue(F&& f)``), except the parameter type. .. note:: - ``h`` should not be empty to avoid undefined behavior. + ``h`` should not be empty to avoid an undefined behavior. diff --git a/source/elements/oneTBB/source/task_scheduler/task_group/task_group_cls.rst b/source/elements/oneTBB/source/task_scheduler/task_group/task_group_cls.rst index 911e76b445..3a3f7c3110 100644 --- a/source/elements/oneTBB/source/task_scheduler/task_group/task_group_cls.rst +++ b/source/elements/oneTBB/source/task_scheduler/task_group/task_group_cls.rst @@ -60,19 +60,19 @@ Member functions 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. + 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 from [function.objects] ISO C++ Standard section. + 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 + 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()``. + **Returns:** ``task_handle`` object pointing to a task to compute ``f()``. .. cpp:function:: template void run( Func&& f ) @@ -82,12 +82,12 @@ Member functions 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 + 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. .. cpp:function:: void run(task_handle&& h) - Schedules the task object pointed by the ``h`` for execution. + Schedules the task object pointed by the ``h`` for the execution. .. note:: The failure to satisfy the following conditions leads to undefined behavior: From e9972536d1e2863bdd8626edaafab3afbe39d482 Mon Sep 17 00:00:00 2001 From: Anton Potapov Date: Thu, 26 Aug 2021 17:53:27 +0300 Subject: [PATCH 03/12] [oneTBB] task_handle related extensions - missing oneapi namespace Co-authored-by: Alexandra --- .../oneTBB/source/task_scheduler/task_group/task_handle.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/source/elements/oneTBB/source/task_scheduler/task_group/task_handle.rst b/source/elements/oneTBB/source/task_scheduler/task_group/task_handle.rst index 7ce8e30d9b..990e27e62e 100644 --- a/source/elements/oneTBB/source/task_scheduler/task_group/task_handle.rst +++ b/source/elements/oneTBB/source/task_scheduler/task_group/task_handle.rst @@ -11,6 +11,7 @@ An instance of ``task_handle`` type owns a deferred task object. .. code:: cpp + namespace oneapi { namespace tbb { class task_handle { @@ -32,6 +33,7 @@ An instance of ``task_handle`` type owns a deferred task object. bool operator!=(std::nullptr_t, task_handle const& h) noexcept; } // namespace tbb + } // namespace oneapi Member Functions From b1e172de1be2df27b4d6221d53c3a2752ae85663 Mon Sep 17 00:00:00 2001 From: Anton Potapov Date: Fri, 27 Aug 2021 15:14:05 +0300 Subject: [PATCH 04/12] [oneTBB] task_handle related extensions - Fixed wording for the move assignment/move constructor of the `task_handle` --- .../oneTBB/source/task_scheduler/task_group/task_handle.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/elements/oneTBB/source/task_scheduler/task_group/task_handle.rst b/source/elements/oneTBB/source/task_scheduler/task_group/task_handle.rst index 990e27e62e..764ba117e1 100644 --- a/source/elements/oneTBB/source/task_scheduler/task_group/task_handle.rst +++ b/source/elements/oneTBB/source/task_scheduler/task_group/task_handle.rst @@ -45,7 +45,7 @@ Member Functions .. cpp:function:: task_handle(task_handle&& src) - Constructs ``task_handle`` object with the content of ``src`` using move semantics. ``src`` is left in an empty state. + Constructs ``task_handle`` object with the content of ``src`` using move semantics. ``src`` becomes empty after the construction. .. cpp:function:: ~task_handle() @@ -53,7 +53,7 @@ Member Functions .. cpp:function:: task_handle& operator=(task_handle&& src) - Replaces the content of ``task_handle`` object with the content of ``src`` using move semantics. ``src`` is left in an empty state. + Replaces the content of ``task_handle`` object with the content of ``src`` using move semantics. ``src`` becomes empty after the assignment. The previously associated task object, if any, is destroyed before the assignment. **Returns:** Reference to ``*this``. From baa71ef236718ead9fd8d0cae9acb21819b69eb9 Mon Sep 17 00:00:00 2001 From: Anton Potapov Date: Mon, 30 Aug 2021 14:07:24 +0300 Subject: [PATCH 05/12] [oneTBB] task_group contructor acepting task_group_context --- .../source/task_scheduler/task_group/task_group_cls.rst | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/source/elements/oneTBB/source/task_scheduler/task_group/task_group_cls.rst b/source/elements/oneTBB/source/task_scheduler/task_group/task_group_cls.rst index 27b2fe1ab4..a4bba597df 100644 --- a/source/elements/oneTBB/source/task_scheduler/task_group/task_group_cls.rst +++ b/source/elements/oneTBB/source/task_scheduler/task_group/task_group_cls.rst @@ -1,5 +1,5 @@ .. SPDX-FileCopyrightText: 2019-2020 Intel Corporation -.. +...................................................... .. SPDX-License-Identifier: CC-BY-4.0 ========== @@ -19,6 +19,8 @@ Tasks can be dynamically added to the group while it is executing. class task_group { public: task_group(); + task_group(task_group_context& context); + ~task_group(); template @@ -44,6 +46,10 @@ Member functions Constructs an empty ``task_group``. +.. cpp:function:: task_group(task_group_context& context) + + Constructs an empty ``task_group``, which tasks are associated with the ``context``. + .. cpp:function:: ~task_group() Destroys the ``task_group``. From bfc85b24d4b8fbfe78a3bfad08e18f69fd6b1d84 Mon Sep 17 00:00:00 2001 From: Anton Potapov Date: Wed, 1 Sep 2021 08:28:44 +0300 Subject: [PATCH 06/12] [oneTBB] task_group contructor acepting task_group_context - Fixed wording Co-authored-by: Alexandra --- .../oneTBB/source/task_scheduler/task_group/task_group_cls.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/elements/oneTBB/source/task_scheduler/task_group/task_group_cls.rst b/source/elements/oneTBB/source/task_scheduler/task_group/task_group_cls.rst index a4bba597df..126ad2979c 100644 --- a/source/elements/oneTBB/source/task_scheduler/task_group/task_group_cls.rst +++ b/source/elements/oneTBB/source/task_scheduler/task_group/task_group_cls.rst @@ -48,7 +48,7 @@ Member functions .. cpp:function:: task_group(task_group_context& context) - Constructs an empty ``task_group``, which tasks are associated with the ``context``. + Constructs an empty ``task_group``. All tasks added into the ``task_group`` are associated with the ``context``. .. cpp:function:: ~task_group() From 121649e636e613d4d9c80789369d1db87f8115e5 Mon Sep 17 00:00:00 2001 From: Anton Potapov Date: Wed, 1 Sep 2021 10:55:51 +0300 Subject: [PATCH 07/12] [oneTBB] task_handle related extensions - Fixed RST syntaz Co-authored-by: Alexandra --- .../oneTBB/source/task_scheduler/task_group/task_handle.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/elements/oneTBB/source/task_scheduler/task_group/task_handle.rst b/source/elements/oneTBB/source/task_scheduler/task_group/task_handle.rst index 764ba117e1..17dc6c5ff2 100644 --- a/source/elements/oneTBB/source/task_scheduler/task_group/task_handle.rst +++ b/source/elements/oneTBB/source/task_scheduler/task_group/task_handle.rst @@ -72,11 +72,11 @@ Non-Member Functions bool operator==(task_handle const& h, std::nullptr_t) noexcept bool operator==(std::nullptr_t, task_handle const& h) noexcept - **Returns**: ``true`` if ``h`` is empty, ``false`` otherwise. +**Returns**: ``true`` if ``h`` is empty, ``false`` otherwise. .. code:: cpp bool operator!=(task_handle const& h, std::nullptr_t) noexcept bool operator!=(std::nullptr_t, task_handle const& h) noexcept - **Returns**: ``true`` if ``h`` is not empty, ``false`` otherwise. \ No newline at end of file +**Returns**: ``true`` if ``h`` is not empty, ``false`` otherwise. \ No newline at end of file From 85a9d7f156429a2e0fc2f487d7180e038233ea2a Mon Sep 17 00:00:00 2001 From: Anton Potapov Date: Wed, 1 Sep 2021 11:08:41 +0300 Subject: [PATCH 08/12] [oneTBB] task_handle related extensions - removed scheduler bypass mentions --- .../task_scheduler/task_group/task_group_cls.rst | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/source/elements/oneTBB/source/task_scheduler/task_group/task_group_cls.rst b/source/elements/oneTBB/source/task_scheduler/task_group/task_group_cls.rst index 3a3f7c3110..5400810818 100644 --- a/source/elements/oneTBB/source/task_scheduler/task_group/task_group_cls.rst +++ b/source/elements/oneTBB/source/task_scheduler/task_group/task_group_cls.rst @@ -66,12 +66,6 @@ Member functions 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 a task to compute ``f()``. .. cpp:function:: template void run( Func&& f ) @@ -79,12 +73,6 @@ Member functions Adds a task to compute ``f()`` and returns immediately. The ``Func`` type must meet the `Function Objects` requirements from [function.objects] ISO C++ Standard section. - 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. - .. cpp:function:: void run(task_handle&& h) Schedules the task object pointed by the ``h`` for the execution. From 0bb320306c34317f4b728aea09274a08c8eea11d Mon Sep 17 00:00:00 2001 From: Anton Potapov Date: Tue, 7 Sep 2021 12:07:15 +0300 Subject: [PATCH 09/12] [oneTBB] task_handle related extensions - task_group::run_and_wait(task_handle&&) metgod Signed-off-by: Anton Potapov --- .../task_group/task_group_cls.rst | 23 +++++++++++++++---- 1 file changed, 18 insertions(+), 5 deletions(-) diff --git a/source/elements/oneTBB/source/task_scheduler/task_group/task_group_cls.rst b/source/elements/oneTBB/source/task_scheduler/task_group/task_group_cls.rst index 1b5b5e892e..832ef708cc 100644 --- a/source/elements/oneTBB/source/task_scheduler/task_group/task_group_cls.rst +++ b/source/elements/oneTBB/source/task_scheduler/task_group/task_group_cls.rst @@ -24,7 +24,7 @@ Tasks can be dynamically added to the group while it is executing. ~task_group(); template - void run( Func&& f ); + void run(Func&& f); template task_handle defer(Func&& f); @@ -32,7 +32,9 @@ Tasks can be dynamically added to the group while it is executing. void run(task_handle&& h); template - task_group_status run_and_wait( const Func& f ); + task_group_status run_and_wait(const Func& f); + + task_group_status run_and_wait(task_handle&& h); task_group_status wait(); void cancel(); @@ -74,7 +76,7 @@ Member functions **Returns:** ``task_handle`` object pointing to a task to compute ``f()``. -.. cpp:function:: template void run( Func&& f ) +.. cpp:function:: template void run(Func&& f) Adds a task to compute ``f()`` and returns immediately. The ``Func`` type must meet the `Function Objects` requirements from [function.objects] ISO C++ Standard section. @@ -88,13 +90,24 @@ Member functions * ``h`` is not empty. * ``*this`` is the same ``task_group`` that ``h`` is created with. -.. cpp:function:: template task_group_status run_and_wait( const Func& f ) +.. cpp:function:: template task_group_status run_and_wait(const Func& f) - Equivalent to ``{run(f); return wait();}``, but guarantees that ``f()`` runs on the current thread. + Equivalent to ``{run(f); return wait();}``. The ``Func`` type must meet the `Function Objects` requirements from the [function.objects] ISO C++ Standard section. **Returns**: The status of ``task_group``. See :doc:`task_group_status `. +.. cpp:function::task_group_status run_and_wait(task_handle&& h) + + Equivalent to ``{run(h); return wait();}``. + + .. note:: + 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. + + **Returns**: The status of ``task_group``. See :doc:`task_group_status `. + .. cpp:function:: task_group_status wait() Waits for all tasks in the group to complete or be cancelled. From 2225ba0da12718ae4cf62bf4c1efc1ebd0f74e1a Mon Sep 17 00:00:00 2001 From: Anton Potapov Date: Wed, 8 Sep 2021 13:02:38 +0300 Subject: [PATCH 10/12] [oneTBB] task_handle related extensions - fixed license header date - fixed syntax Signed-off-by: Anton Potapov --- source/elements/oneTBB/source/task_scheduler.rst | 2 +- .../source/task_scheduler/task_arena/task_arena_cls.rst | 3 ++- .../source/task_scheduler/task_arena/this_task_arena_ns.rst | 2 +- .../source/task_scheduler/task_group/task_group_cls.rst | 4 ++-- .../oneTBB/source/task_scheduler/task_group/task_handle.rst | 4 ++-- 5 files changed, 8 insertions(+), 7 deletions(-) diff --git a/source/elements/oneTBB/source/task_scheduler.rst b/source/elements/oneTBB/source/task_scheduler.rst index 01491cfb77..5f185f3a2a 100644 --- a/source/elements/oneTBB/source/task_scheduler.rst +++ b/source/elements/oneTBB/source/task_scheduler.rst @@ -1,4 +1,4 @@ -.. SPDX-FileCopyrightText: 2019-2020 Intel Corporation +.. SPDX-FileCopyrightText: 2019-2021 Intel Corporation .. .. SPDX-License-Identifier: CC-BY-4.0 diff --git a/source/elements/oneTBB/source/task_scheduler/task_arena/task_arena_cls.rst b/source/elements/oneTBB/source/task_scheduler/task_arena/task_arena_cls.rst index 5288e8ebdb..a6130b697b 100644 --- a/source/elements/oneTBB/source/task_scheduler/task_arena/task_arena_cls.rst +++ b/source/elements/oneTBB/source/task_scheduler/task_arena/task_arena_cls.rst @@ -1,4 +1,4 @@ -.. SPDX-FileCopyrightText: 2019-2020 Intel Corporation +.. SPDX-FileCopyrightText: 2019-2021 Intel Corporation .. .. SPDX-License-Identifier: CC-BY-4.0 @@ -261,6 +261,7 @@ Member functions .. note:: ``h`` should not be empty to avoid an undefined behavior. + Example ------- diff --git a/source/elements/oneTBB/source/task_scheduler/task_arena/this_task_arena_ns.rst b/source/elements/oneTBB/source/task_scheduler/task_arena/this_task_arena_ns.rst index 4cf3ee50c3..80b6751155 100644 --- a/source/elements/oneTBB/source/task_scheduler/task_arena/this_task_arena_ns.rst +++ b/source/elements/oneTBB/source/task_scheduler/task_arena/this_task_arena_ns.rst @@ -1,4 +1,4 @@ -.. SPDX-FileCopyrightText: 2019-2020 Intel Corporation +.. SPDX-FileCopyrightText: 2019-2021 Intel Corporation .. .. SPDX-License-Identifier: CC-BY-4.0 diff --git a/source/elements/oneTBB/source/task_scheduler/task_group/task_group_cls.rst b/source/elements/oneTBB/source/task_scheduler/task_group/task_group_cls.rst index 832ef708cc..e4057bac11 100644 --- a/source/elements/oneTBB/source/task_scheduler/task_group/task_group_cls.rst +++ b/source/elements/oneTBB/source/task_scheduler/task_group/task_group_cls.rst @@ -1,5 +1,5 @@ -.. SPDX-FileCopyrightText: 2019-2020 Intel Corporation -...................................................... +.. SPDX-FileCopyrightText: 2019-2021 Intel Corporation +.. .. SPDX-License-Identifier: CC-BY-4.0 ========== diff --git a/source/elements/oneTBB/source/task_scheduler/task_group/task_handle.rst b/source/elements/oneTBB/source/task_scheduler/task_group/task_handle.rst index 17dc6c5ff2..3d87361337 100644 --- a/source/elements/oneTBB/source/task_scheduler/task_group/task_handle.rst +++ b/source/elements/oneTBB/source/task_scheduler/task_group/task_handle.rst @@ -1,5 +1,5 @@ -.. SPDX-FileCopyrightText: 2019-2020 Intel Corporation -...................................................... +.. SPDX-FileCopyrightText: 2021 Intel Corporation +.. .. SPDX-License-Identifier: CC-BY-4.0 =========== From b2f1937734f53d0366cb8de1a3a25605b0d55ab0 Mon Sep 17 00:00:00 2001 From: Anton Potapov Date: Fri, 10 Sep 2021 18:21:48 +0300 Subject: [PATCH 11/12] [oneTBB] task_handle related extensions - aded namespce directive to this_task_arena functions description Signed-off-by: Anton Potapov --- .../source/task_scheduler/task_arena/this_task_arena_ns.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/source/elements/oneTBB/source/task_scheduler/task_arena/this_task_arena_ns.rst b/source/elements/oneTBB/source/task_scheduler/task_arena/this_task_arena_ns.rst index 80b6751155..3e4e9e6276 100644 --- a/source/elements/oneTBB/source/task_scheduler/task_arena/this_task_arena_ns.rst +++ b/source/elements/oneTBB/source/task_scheduler/task_arena/this_task_arena_ns.rst @@ -1,5 +1,5 @@ .. SPDX-FileCopyrightText: 2019-2021 Intel Corporation -.. +...................................................... .. SPDX-License-Identifier: CC-BY-4.0 =============== @@ -28,6 +28,8 @@ with the ``task_arena`` currently used by the calling thread. } } +.. namespace:: tbb::this_task_arena + .. cpp:function:: int current_thread_index() Returns the thread index in a ``task_arena`` currently used by the calling thread, From 25d14e7ea8f605139bef4a44e6105f3e3aa6ec26 Mon Sep 17 00:00:00 2001 From: Anton Potapov Date: Tue, 14 Sep 2021 15:29:30 +0300 Subject: [PATCH 12/12] [oneTBB] task_handle related extensions - fixed typo Signed-off-by: Anton Potapov --- .../source/task_scheduler/task_arena/this_task_arena_ns.rst | 6 +++--- .../oneTBB/source/task_scheduler/task_group/task_handle.rst | 2 ++ 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/source/elements/oneTBB/source/task_scheduler/task_arena/this_task_arena_ns.rst b/source/elements/oneTBB/source/task_scheduler/task_arena/this_task_arena_ns.rst index 3e4e9e6276..bf727eebce 100644 --- a/source/elements/oneTBB/source/task_scheduler/task_arena/this_task_arena_ns.rst +++ b/source/elements/oneTBB/source/task_scheduler/task_arena/this_task_arena_ns.rst @@ -1,5 +1,5 @@ -.. SPDX-FileCopyrightText: 2019-2021 Intel Corporation -...................................................... +.. SPDX-FileCopyrightText: 2019-2020 Intel Corporation +.. .. SPDX-License-Identifier: CC-BY-4.0 =============== @@ -86,4 +86,4 @@ with the ``task_arena`` currently used by the calling thread. The behavior of this function is identical to the generic version (``template void enqueue(F&& f)``), except the parameter type. .. note:: - ``h`` should not be empty to avoid an undefined behavior. + ``h`` should not be empty to avoid an undefined behavior. diff --git a/source/elements/oneTBB/source/task_scheduler/task_group/task_handle.rst b/source/elements/oneTBB/source/task_scheduler/task_group/task_handle.rst index 3d87361337..2b4ee830dd 100644 --- a/source/elements/oneTBB/source/task_scheduler/task_group/task_handle.rst +++ b/source/elements/oneTBB/source/task_scheduler/task_group/task_handle.rst @@ -39,6 +39,8 @@ An instance of ``task_handle`` type owns a deferred task object. Member Functions ---------------- +.. namespace:: tbb::task_handle + .. cpp:function:: task_handle() Creates an empty ``task_handle`` object.