From fd76f452157ec53c7112be199941f26800b3699e Mon Sep 17 00:00:00 2001 From: Anton Potapov Date: Mon, 7 Feb 2022 12:35:20 +0300 Subject: [PATCH] Documentation update for unpreview `task_handle` and related stuff (#755) * Unpreview task_handle and related stuff Signed-off-by: Anton Potapov Co-authored-by: Alexandra --- doc/main/reference/reference.rst | 2 - doc/main/reference/task_arena_extensions.rst | 61 ----------- doc/main/reference/task_group_extensions.rst | 48 ++------- .../task_group_extensions/task_handle.rst | 101 ------------------ .../reference/this_task_arena_extensions.rst | 71 ------------ .../Migration_Guide/Task_API.rst | 6 +- 6 files changed, 13 insertions(+), 276 deletions(-) delete mode 100644 doc/main/reference/task_arena_extensions.rst delete mode 100644 doc/main/reference/task_group_extensions/task_handle.rst delete mode 100644 doc/main/reference/this_task_arena_extensions.rst diff --git a/doc/main/reference/reference.rst b/doc/main/reference/reference.rst index 855c3a869a..8990508206 100644 --- 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 deleted file mode 100644 index 8cde3b29c1..0000000000 --- a/doc/main/reference/task_arena_extensions.rst +++ /dev/null @@ -1,61 +0,0 @@ -.. _task_arena_extensions: - -task_arena extensions -===================== - -.. note:: - To enable these extensions, set the ``TBB_PREVIEW_TASK_GROUP_EXTENSIONS`` macro to 1. - -.. contents:: - :local: - :depth: 1 - -Description -*********** - -|full_name| implementation extends the `tbb::task_arena specification `_ -with an overload of ``enqueue`` method accepting ``task_handle``. - - -API -*** - -Header ------- - -.. code:: cpp - - #include - -Synopsis --------- - -.. code:: cpp - - namespace oneapi { - namespace tbb { - - class task_arena { - public: - void enqueue(task_handle&& h); - }; - - } // namespace tbb - } // namespace oneapi - -Member Functions ----------------- - -.. 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. - -.. rubric:: See also - -* `oneapi::tbb::task_arena specification `_ -* :ref:`task_handle` diff --git a/doc/main/reference/task_group_extensions.rst b/doc/main/reference/task_group_extensions.rst index ea4a7437ef..c2be6acca6 100644 --- 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 `_ 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 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 + task_group_status run_and_wait(const F& f); + //only the requirements for the return type of function F are changed template 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 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 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 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 deleted file mode 100644 index b9b576d430..0000000000 --- a/doc/main/reference/task_group_extensions/task_handle.rst +++ /dev/null @@ -1,101 +0,0 @@ -.. _task_handle: - -task_handle -=========== - -.. note:: To enable these extensions, set the ``TBB_PREVIEW_TASK_GROUP_EXTENSIONS`` macro to 1. - - -.. contents:: - :local: - :depth: 1 - -Description -*********** - -This class owns a deferred task object. - -API -*** - -Header ------- - -.. code:: cpp - - #include - -Synopsis --------- - -.. 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 ----------------- - -.. 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. - diff --git a/doc/main/reference/this_task_arena_extensions.rst b/doc/main/reference/this_task_arena_extensions.rst deleted file mode 100644 index ddd0c31439..0000000000 --- a/doc/main/reference/this_task_arena_extensions.rst +++ /dev/null @@ -1,71 +0,0 @@ -.. _this_task_arena_extensions: - -this_task_arena extensions -========================== - -.. note:: - To enable these extensions, set the ``TBB_PREVIEW_TASK_GROUP_EXTENSIONS`` macro to 1. - -.. contents:: - :local: - :depth: 1 - -Description -*********** - -|full_name| implementation extends the `tbb::this_task_arena specification `_ -with an overloaded ``enqueue`` function. - - -API -*** - -Header ------- - -.. code:: cpp - - #include - -Synopsis --------- - -.. code:: cpp - - namespace oneapi { - namespace tbb { - namespace this_task_arena { - void enqueue(task_handle&& h); - - template - void enqueue(F&& f) ; - } // namespace this_task_arena - } // namespace tbb - } // namespace oneapi - -Member Functions ----------------- - - -.. 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 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`` 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. - - -.. rubric:: See also: - -* `oneapi::tbb::this_task_arena specification `_ -* `oneapi::tbb::task_arena specification `_ -* :ref:`task_handle` diff --git a/doc/main/tbb_userguide/Migration_Guide/Task_API.rst b/doc/main/tbb_userguide/Migration_Guide/Task_API.rst index 08d66b5c82..cdf922a316 100644 --- 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 // 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 int main(){