[oneTBB] task_group/task_arena extensions

source/elements/oneTBB/source/task_scheduler.rst

@@ -47,6 +47,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
 ----------

source/elements/oneTBB/source/task_scheduler/task_arena/task_arena_cls.rst

@@ -14,17 +14,17 @@ A class that represents an explicit, user-managed task scheduler arena.
     // Defined in header <oneapi/tbb/task_arena.h>
 
     namespace oneapi {
-    namespace tbb {
-
-        class task_arena {
-        public:
-            static const int automatic = /* unspecified */;
-            static const int not_initialized = /* unspecified */;
-            enum class priority : /* unspecified type */ {
-                low = /* unspecified */,
-                normal = /* unspecified */,
-                high = /* unspecified */
-            };
+        namespace tbb {
+
+            class task_arena {
+            public:
+                static const int automatic = /* unspecified */;
+                static const int not_initialized = /* unspecified */;
+                enum class priority : /* unspecified type */ {
+                    low = /* unspecified */,
+                    normal = /* unspecified */,
+                    high = /* unspecified */
+                };
 
                 struct constraints {
                     numa_node_id numa_node;
@@ -42,23 +42,25 @@ A class that represents an explicit, user-managed task scheduler arena.
                 explicit task_arena(oneapi::tbb::attach);
                 ~task_arena();
 
-            void initialize();
-            void initialize(int max_concurrency, unsigned reserved_for_masters = 1,
-                            priority a_priority = priority::normal);
-            void initialize(constraints a_constraints, unsigned reserved_for_masters = 1,
-                            priority a_priority = priority::normal);
+                void initialize();
+                void initialize(int max_concurrency, unsigned reserved_for_masters = 1,
+                                priority a_priority = priority::normal);
+                void initialize(constraints a_constraints, unsigned reserved_for_masters = 1,
+                                priority a_priority = priority::normal);
                 void initialize(oneapi::tbb::attach);
 
-            void terminate();
+                void terminate();
+
+                bool is_active() const;
+                int max_concurrency() const;
 
-            bool is_active() const;
-            int max_concurrency() const;
+                template<typename F> auto execute(F&& f) -> decltype(f());
+                template<typename F> void enqueue(F&& f);
 
-            template<typename F> auto execute(F&& f) -> decltype(f());
-            template<typename F> void enqueue(F&& f);
-        };
+                void enqueue(task_handle&& h);
+            };
 
-    } // namespace tbb
+        } // namespace tbb
     } // namespace oneapi
 
 A ``task_arena`` class represents a place where threads may share and execute tasks.
@@ -249,6 +251,15 @@ 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 processing. 
+
+    The behavior of this function is identical to the generic version (``template<typename F> void task_arena::enqueue(F&& f)``), except parameter type. 
+
+    .. note:: 
+       ``h`` should not be empty to avoid an undefined behavior.
+
 Example
 -------
 

source/elements/oneTBB/source/task_scheduler/task_arena/this_task_arena_ns.rst

@@ -22,10 +22,16 @@ with the ``task_arena`` currently used by the calling thread.
             int current_thread_index();
             int max_concurrency();
             template<typename F> auto isolate(F&& f) -> decltype(f());
+
+            void enqueue(task_handle&& h);
+
+            template<typename F> void enqueue(F&& f) ;
         }
     } // namespace tbb
     } // namespace oneapi 
 
+.. 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,
@@ -67,3 +73,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<typename F> void enqueue(F&& f)
+
+    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<typename F> 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.
+
+    The behavior of this function is identical to the generic version (``template<typename F> void enqueue(F&& f)``), except the parameter type. 
+
+    .. note:: 
+        ``h`` should not be empty to avoid an undefined behavior.

source/elements/oneTBB/source/task_scheduler/task_group/task_group_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
 
@@ -20,13 +20,22 @@ 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<typename Func>
-            void run( Func&& f );
+            void run(Func&& f);
+
+            template<typename Func>
+            task_handle defer(Func&& f);
+
+            void run(task_handle&& h);
 
             template<typename Func>
-            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();
@@ -46,25 +55,61 @@ Member functions
 
     Constructs an empty ``task_group``.
 
+.. cpp:function:: task_group(task_group_context& context)
+
+    Constructs an empty ``task_group``. All tasks added into the ``task_group`` are associated with the ``context``.
+
 .. cpp:function:: ~task_group()
 
     Destroys the ``task_group``.
 
     **Requires**: Method ``wait`` must be called before destroying a ``task_group``,
     otherwise, the destructor throws an exception.
 
-.. cpp:function:: template<typename Func> void run( Func&& f )
+.. cpp:function:: 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 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 described in the [function.objects] section of the ISO C++ standard.
+
+    **Returns:** ``task_handle`` object pointing to a task to compute ``f()``.
+
+.. cpp:function:: template<typename Func> 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.
+
+.. cpp:function:: void run(task_handle&& h)
+
+    Schedules the task object pointed by the ``h`` for the 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<typename Func> task_group_status run_and_wait( const Func& f )
+.. cpp:function:: template<typename Func> 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 <task_group_status_enum>`.
 
+.. 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 <task_group_status_enum>`.
+
 .. cpp:function:: task_group_status wait()
 
     Waits for all tasks in the group to complete or be cancelled.

source/elements/oneTBB/source/task_scheduler/task_group/task_handle.rst

@@ -0,0 +1,84 @@
+.. SPDX-FileCopyrightText: 2021 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 oneapi {
+   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
+   } // namespace oneapi
+
+
+Member Functions
+----------------
+
+.. namespace:: tbb::task_handle
+
+.. 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`` becomes empty after the construction. 
+
+.. 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`` becomes empty after the assignment.
+    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.