Documentation update for unpreview task_handle and related stuff (#755

) * Unpreview task_handle and related stuff Signed-off-by: Anton Potapov <anton.potapov@intel.com> Co-authored-by: Alexandra <alexandra.epanchinzeva@intel.com>
uxlfoundation · Feb 7, 2022 · fd76f45 · fd76f45
1 parent 3a7f96d
commit fd76f45
Show file tree

Hide file tree

Showing 6 changed files with 13 additions and 276 deletions.
diff --git a/doc/main/reference/reference.rst b/doc/main/reference/reference.rst
@@ -50,6 +50,4 @@ The key properties of a preview feature are:
     constraints_extensions
     info_namespace_extensions
     task_group_extensions
-    task_arena_extensions
-    this_task_arena_extensions
     custom_mutex_chmap
diff --git a/doc/main/reference/task_arena_extensions.rst b/doc/main/reference/task_arena_extensions.rst
diff --git a/doc/main/reference/task_group_extensions.rst b/doc/main/reference/task_group_extensions.rst
@@ -15,8 +15,6 @@ Description
 
 |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:
 
-  - constructor that takes a custom ``tbb::task_group_context`` object as an argument
-  - methods to create and run deferred tasks with ``task_handle`` 
   - requirements for a user-provided function object
 
 
@@ -40,15 +38,15 @@ Synopsis
    
            class task_group {
            public:
-               task_group(task_group_context& context);
-               
+
+               //only the requirements for the return type of function F are changed              
                template<typename F>
                task_handle defer(F&& f);
                    
-               void run(task_handle&& h);
-               
-               task_group_status run_and_wait(task_handle&&);
-
+               //only the requirements for the return type of function F are changed
+               template<typename F>
+               task_group_status run_and_wait(const F& f);
+    
                //only the requirements for the return type of function F are changed              
                template<typename F>
                void run(F&& f);
@@ -62,43 +60,19 @@ Synopsis
 Member Functions
 ----------------
 
-.. cpp:function:: task_group(task_group_context& context)
-
-Constructs an empty ``task_group``, which tasks are associated with the ``context``.
-
-
 .. 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 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 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 task to compute ``f()``.
-
-
-.. cpp:function:: void run(task_handle&& h)
-
-Schedules the task object pointed by the ``h`` for execution.
+   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. 
 
-.. caution:: If ``h`` is empty or ``*this`` is not the same ``task_group`` that ``h`` is created with, the behavior is undefined.
+.. cpp:function:: template<typename F> task_group_status run_and_wait(const F& f)
 
+As an optimization hint, ``F`` might return a ``task_handle``, which task object can be executed next.
 
-.. cpp:function:: task_group_status run_and_wait(task_handle&& h)
-
-Equivalent to ``{run(std::move(h)); return wait();}``.
-
-**Returns**: The status of ``task_group``.
-
-.. caution::
-   If ``h`` is empty or ``*this`` is not the same ``task_group`` that ``h`` is created with, the behavior is undefined.
+.. note::
+   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. 
 
 
 .. cpp:function:: template<typename F> void  run(F&& f)

diff --git a/doc/main/reference/task_group_extensions/task_handle.rst b/doc/main/reference/task_group_extensions/task_handle.rst
diff --git a/doc/main/reference/this_task_arena_extensions.rst b/doc/main/reference/this_task_arena_extensions.rst
diff --git a/doc/main/tbb_userguide/Migration_Guide/Task_API.rst b/doc/main/tbb_userguide/Migration_Guide/Task_API.rst
@@ -364,11 +364,10 @@ is not guaranteed to be executed next by the current thread.
         root.wait_for_all();;
     }
 
-In oneTBB this can be done using the preview feature of ``oneapi::tbb::task_group``. 
+In oneTBB, this can be done using ``oneapi::tbb::task_group``. 
 
 .. code:: cpp
    
-    #define TBB_PREVIEW_TASK_GROUP_EXTENSIONS 1
     #include <oneapi/tbb/task_group.h>
     
     // Assuming OtherTask is defined.
@@ -421,11 +420,10 @@ and waiting on it is implemented as follows:
         // i.e. after the callback is called  
     }
 
-In oneTBB this can be done using the preview feature of ``oneapi::tbb::task_group``.
+In oneTBB, this can be done using ``oneapi::tbb::task_group``.
 
 .. code:: cpp
 
-    #define TBB_PREVIEW_TASK_GROUP_EXTENSIONS 1
     #include <oneapi/tbb/task_group.h>
 
     int main(){