From e711a65e4950f114baacc2df3214e4a06862587f Mon Sep 17 00:00:00 2001 From: Alexei Katranov Date: Tue, 24 Aug 2021 12:06:50 +0300 Subject: [PATCH 01/13] Add task_scheduler_handle Signed-off-by: Alexei Katranov --- .../elements/oneTBB/source/task_scheduler.rst | 10 ++ .../source/task_scheduler/attach_tag_type.rst | 24 +++ .../task_scheduler_handle_cls.rst | 156 ++++++++++++++++++ .../task_arena/task_arena_cls.rst | 43 ++++- 4 files changed, 228 insertions(+), 5 deletions(-) create mode 100644 source/elements/oneTBB/source/task_scheduler/attach_tag_type.rst create mode 100644 source/elements/oneTBB/source/task_scheduler/scheduling_controls/task_scheduler_handle_cls.rst diff --git a/source/elements/oneTBB/source/task_scheduler.rst b/source/elements/oneTBB/source/task_scheduler.rst index a4bd41addf..9d5bd80c87 100644 --- a/source/elements/oneTBB/source/task_scheduler.rst +++ b/source/elements/oneTBB/source/task_scheduler.rst @@ -37,6 +37,7 @@ Scheduling controls task_scheduler/scheduling_controls/task_group_context_cls.rst task_scheduler/scheduling_controls/global_control_cls.rst task_scheduler/scheduling_controls/resumable_tasks.rst + task_scheduler/scheduling_controls/task_scheduler_handle_cls.rst Task Group ---------- @@ -56,3 +57,12 @@ Task Arena task_scheduler/task_arena/task_arena_cls.rst task_scheduler/task_arena/this_task_arena_ns.rst task_scheduler/task_arena/task_scheduler_observer_cls.rst + +Helper types +------------ + +.. toctree:: + :titlesonly: + + task_scheduler/attach_tag_type.rst + diff --git a/source/elements/oneTBB/source/task_scheduler/attach_tag_type.rst b/source/elements/oneTBB/source/task_scheduler/attach_tag_type.rst new file mode 100644 index 0000000000..52d8164f39 --- /dev/null +++ b/source/elements/oneTBB/source/task_scheduler/attach_tag_type.rst @@ -0,0 +1,24 @@ +.. SPDX-FileCopyrightText: 2021 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +=============== +attach tag type +=============== +**[scheduler.attach]** + +An ``attach`` tag type is specifically used with ``task_arena`` and +``task_scheduler_handle`` interfaces. It is guaranteed to be default constructible. + +.. code:: cpp + + namespace oneapi { + namespace tbb { + using attach = /* unspecified */ + } + } + +See also: + +* :doc:`task_arena ` +* :doc:`task_scheduler_handle ` \ No newline at end of file diff --git a/source/elements/oneTBB/source/task_scheduler/scheduling_controls/task_scheduler_handle_cls.rst b/source/elements/oneTBB/source/task_scheduler/scheduling_controls/task_scheduler_handle_cls.rst new file mode 100644 index 0000000000..0bc5119e13 --- /dev/null +++ b/source/elements/oneTBB/source/task_scheduler/scheduling_controls/task_scheduler_handle_cls.rst @@ -0,0 +1,156 @@ +.. SPDX-FileCopyrightText: 2021 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +===================== +task_scheduler_handle +===================== +**[scheduler.task_scheduler_handle]** + +The ``oneapi::tbb::task_scheduler_handle`` class and the ``oneapi::tbb::finalize`` function allow to wait for completion of worker threads. + +When the ``oneapi::tbb::finalize`` function is called with an ``oneapi::tbb::task_scheduler_handle`` instance, it blocks the calling +thread until the completion of all worker threads that were implicitly created by the library. + + +.. code:: cpp + + // Defined in header + + namespace oneapi { + namespace tbb { + + using attach = /* unspecified */ + + class task_scheduler_handle { + public: + task_scheduler_handle() = default; + task_scheduler_handle(oneapi::tbb::attach); + ~task_scheduler_handle(); + + task_scheduler_handle(const task_scheduler_handle& other) = delete; + task_scheduler_handle(task_scheduler_handle&& other) noexcept; + task_scheduler_handle& operator=(const task_scheduler_handle& other) = delete; + task_scheduler_handle& operator=(task_scheduler_handle&& other) noexcept; + + explicit operator bool() const noexcept; + + void release(); + }; + + void finalize(task_scheduler_handle& handle); + bool finalize(task_scheduler_handle& handle, const std::nothrow_t&) noexcept; + + } // namespace tbb + } // namespace oneapi + +Member Functions +---------------- + +.. cpp:function:: task_scheduler_handle() + + **Effects**: Creates an instance of the ``task_scheduler_handle`` class that does not contain any reference to the task scheduler. + +------------------------------------------------------- + +.. cpp:function:: task_scheduler_handle(oneapi::tbb::attach) + + **Effects**: Creates an instance of the ``task_scheduler_handle`` class that holds a reference to the task scheduler preventing + its premature destruction. + +------------------------------------------------------- + +.. cpp:function:: ~task_scheduler_handle() + + **Effects**: Destroys an instance of the ``task_scheduler_handle`` class. + Releases a reference to the task scheduler and deactivates an instance of the ``task_scheduler_handle`` class. + +------------------------------------------------------- + +.. cpp:function:: task_scheduler_handle(task_scheduler_handle&& other) noexcept + + **Effects**: Creates an instance of the ``task_scheduler_handle`` class that references the task scheduler referenced by ``other``. In turn, ``other`` releases its reference to the task scheduler. + +------------------------------------------------------- + +.. cpp:function:: task_scheduler_handle& operator=(task_scheduler_handle&& other) noexcept + + **Effects**: Releases a reference to the task scheduler referenced by ``this``. Adds a reference to the task scheduler referenced by ``other``. + In turn, ``other`` releases its reference to the task scheduler. + +------------------------------------------------------- + +.. cpp:function:: explicit operator bool() const noexcept + + **Returns**: ``true`` if ``this`` references any task scheduler; ``false`` otherwise. + +------------------------------------------------------- + +.. cpp:function:: void release() + + **Effects**: Releases a reference to the task scheduler and deactivates an instance of the ``task_scheduler_handle`` + class. Non-blocking method. + +Non-member Functions +-------------------- + +.. cpp:function:: void finalize(task_scheduler_handle& handle) + + **Effects**: Blocks the program execution until all worker threads have been completed. Throws the ``oneapi::tbb::unsafe_wait`` + exception if it is not safe to wait for the completion of the worker threads. + +The following conditions should be met for finalization to succeed: + +- No active (not yet terminated) instances of class ``task_arena`` exist in the whole program; +- ``task_scheduler_handle::release`` is called for each other active instance of class ``task_scheduler_handle``, possibly by different application threads. + +Under these conditions, it is guaranteed that at least one ``finalize`` call succeeds, +at which point all worker threads have been completed. +If calls are performed simultaneously, more than one call might succeed. + +.. note:: + + If you know how many active ``task_scheduler_handle`` instances exist in the program, + it is necessary to ``release`` all but the last one, then call ``finalize`` for + the last instance. + +.. caution:: + + The method always fails if called within a task, a parallel algorithm, or a flow graph node. + +------------------------------------------------------- + +.. cpp:function:: bool finalize(task_scheduler_handle& handle, const std::nothrow_t&) noexcept + + **Effects**: Blocks the program execution until all worker threads have been completed. Same as above, but returns ``true`` if all worker + threads have been completed successfully, or ``false`` if it is not safe to wait for the completion of the worker threads. + +Examples +-------- + +.. code:: cpp + + #include + #include + + #include + + int main() { + oneapi::tbb::task_scheduler_handle handle; + + handle = oneapi::tbb::task_scheduler_handle{oneapi::tbb::attach{}}; + + // Do some parallel work here, e.g. + oneapi::tbb::parallel_for(0, 10000, [](int){}); + try { + oneapi::tbb::finalize(handle); + // oneTBB worker threads are terminated at this point. + } catch (const oneapi::tbb::unsafe_wait&) { + std::cerr << "Failed to terminate the worker threads." << std::endl; + } + return 0; + } + +See also: + +* :doc:`attach <../attach_tag_type>` \ No newline at end of file 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..73ce9394ac 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 @@ -15,6 +15,8 @@ A class that represents an explicit, user-managed task scheduler arena. namespace tbb { + using attach = /* unspecified */ + class task_arena { public: static const int automatic = /* unspecified */; @@ -24,7 +26,7 @@ A class that represents an explicit, user-managed task scheduler arena. normal = /* unspecified */, high = /* unspecified */ }; - struct attach {}; + struct attach {}; /* Deprecated (compatibility with oneTBB Specification 1.0), use oneapi::tbb::attach */ struct constraints { numa_node_id numa_node; int max_concurrency; @@ -38,7 +40,8 @@ A class that represents an explicit, user-managed task scheduler arena. task_arena(constraints a_constraints, unsigned reserved_for_masters = 1, priority a_priority = priority::normal); task_arena(const task_arena &s); - explicit task_arena(task_arena::attach); + explicit task_arena(oneapi::tbb::attach); + explicit task_arena(task_arena::attach); /* Deprecated (compatibility with oneTBB Specification 1.0), use oneapi::tbb::attach version */ ~task_arena(); void initialize(); @@ -46,7 +49,9 @@ A class that represents an explicit, user-managed task scheduler arena. priority a_priority = priority::normal); void initialize(constraints a_constraints, unsigned reserved_for_masters = 1, priority a_priority = priority::normal); - void initialize(task_arena::attach); + void initialize(oneapi::tbb::attach); + void initialize(task_arena::attach); /* Deprecated (compatibility with oneTBB Specification 1.0), use oneapi::tbb::attach version */ + void terminate(); bool is_active() const; @@ -108,6 +113,10 @@ Member types and constants A tag for constructing a ``task_arena`` with attach. + .. caution:: + + ``struct attach`` is deprecated (compatibility with oneTBB Specification 1.0), use oneapi::tbb::attach + .. cpp:struct:: constraints Represents limitations applied to threads within ``task_arena``. @@ -158,6 +167,16 @@ Member functions Copies settings from another ``task_arena`` instance. +.. cpp:function:: explicit task_arena(oneapi::tbb::attach) + + Creates an instance of ``task_arena`` that is connected to the internal task arena representation currently used by the calling thread. + If no such arena exists yet, creates a ``task_arena`` with default parameters. + + .. note:: + + Unlike other constructors, this one automatically initializes + the new ``task_arena`` when connecting to an already existing arena. + .. cpp:function:: explicit task_arena(task_arena::attach) Creates an instance of ``task_arena`` that is connected to the internal task arena representation currently used by the calling thread. @@ -168,6 +187,10 @@ Member functions Unlike other constructors, this one automatically initializes the new ``task_arena`` when connecting to an already existing arena. + .. caution:: + + ``struct attach`` is deprecated (compatibility with oneTBB Specification 1.0), use oneapi::tbb::attach version + .. cpp:function:: ~task_arena() Destroys the ``task_arena`` instance, but the destruction may not be synchronized with any task execution inside this ``task_arena``. @@ -190,13 +213,22 @@ Member functions Same as above. +.. cpp:function:: void initialize(oneapi::tbb::attach) + + If an internal task arena representation currently used by the calling thread, the method ignores arena + parameters and connects ``task_arena`` to that internal task arena representation. + The method has no effect when called for an already initialized ``task_arena``. + .. cpp:function:: void initialize(task_arena::attach) - If an instance of class ``task_arena::attach`` is specified as the argument, and there is - an internal task arena representation currently used by the calling thread, the method ignores arena + If an internal task arena representation currently used by the calling thread, the method ignores arena parameters and connects ``task_arena`` to that internal task arena representation. The method has no effect when called for an already initialized ``task_arena``. + .. caution:: + + ``struct attach`` is deprecated (compatibility with oneTBB Specification 1.0), use oneapi::tbb::attach version + .. cpp:function:: void terminate() Removes the reference to the internal task arena representation without destroying the @@ -293,5 +325,6 @@ to the corresponding NUMA node. See also: +* :doc:`attach <../attach_tag_type>` * :doc:`task_group <../task_group/task_group_cls>` * :doc:`task_scheduler_observer ` From 83e1230c92b779bcf5c9425987a296ea6d6bedf5 Mon Sep 17 00:00:00 2001 From: Alex Date: Mon, 30 Aug 2021 16:05:35 +0300 Subject: [PATCH 02/13] Update source/elements/oneTBB/source/task_scheduler/scheduling_controls/task_scheduler_handle_cls.rst Co-authored-by: kboyarinov --- .../scheduling_controls/task_scheduler_handle_cls.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/source/elements/oneTBB/source/task_scheduler/scheduling_controls/task_scheduler_handle_cls.rst b/source/elements/oneTBB/source/task_scheduler/scheduling_controls/task_scheduler_handle_cls.rst index 0bc5119e13..d2d6a621c2 100644 --- a/source/elements/oneTBB/source/task_scheduler/scheduling_controls/task_scheduler_handle_cls.rst +++ b/source/elements/oneTBB/source/task_scheduler/scheduling_controls/task_scheduler_handle_cls.rst @@ -78,6 +78,8 @@ Member Functions **Effects**: Releases a reference to the task scheduler referenced by ``this``. Adds a reference to the task scheduler referenced by ``other``. In turn, ``other`` releases its reference to the task scheduler. +**Returns**: A reference to ``*this``. + ------------------------------------------------------- .. cpp:function:: explicit operator bool() const noexcept From d9bf6ccec4c8a08f439d7f641ad790430d678e51 Mon Sep 17 00:00:00 2001 From: Alex Date: Mon, 30 Aug 2021 16:07:10 +0300 Subject: [PATCH 03/13] Update task_scheduler_handle_cls.rst Fix formatting --- .../deprecated/task_arena_attach_tag.rst | 64 +++++++++++++++++++ source/elements/oneTBB/source/index.rst | 6 ++ .../task_scheduler_handle_cls.rst | 28 ++++---- .../task_arena/task_arena_cls.rst | 38 +---------- 4 files changed, 84 insertions(+), 52 deletions(-) create mode 100644 source/elements/oneTBB/source/deprecated/task_arena_attach_tag.rst diff --git a/source/elements/oneTBB/source/deprecated/task_arena_attach_tag.rst b/source/elements/oneTBB/source/deprecated/task_arena_attach_tag.rst new file mode 100644 index 0000000000..5fb0a6f72e --- /dev/null +++ b/source/elements/oneTBB/source/deprecated/task_arena_attach_tag.rst @@ -0,0 +1,64 @@ +.. SPDX-FileCopyrightText: 2019-2020 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +================== +task_arena::attach +================== +**[deprecated.task_arena_attach_tag]** + + .. caution:: + + Deprecated in oneTBB Specification 1.1 + +A set of methods for constructing a task_arena with attach. + +.. code:: cpp + + // Defined in header + + namespace tbb { + + class task_arena { + public: + // ... + struct attach {}; + + explicit task_arena(task_arena::attach); + void initialize(task_arena::attach); + // ... + }; + + } // namespace tbb + + +Member types and constants +-------------------------- + +.. cpp:struct:: attach + + A tag for constructing a task_arena with attach. + +Member functions +---------------- + +.. cpp:function:: explicit task_arena(task_arena::attach) + + Creates an instance of ``task_arena`` that is connected to the internal task arena representation currently used by the calling thread. + If no such arena exists yet, creates a ``task_arena`` with default parameters. + + .. note:: + + Unlike other constructors, this one automatically initializes + the new ``task_arena`` when connecting to an already existing arena. + + +.. cpp:function:: void initialize(task_arena::attach) + + If an internal task arena representation currently used by the calling thread, the method ignores arena + parameters and connects ``task_arena`` to that internal task arena representation. + The method has no effect when called for an already initialized ``task_arena``. + +See also: + +* :doc:`attach <../task_scheduler/attach_tag_type>` diff --git a/source/elements/oneTBB/source/index.rst b/source/elements/oneTBB/source/index.rst index bb5c287120..61d9085829 100644 --- a/source/elements/oneTBB/source/index.rst +++ b/source/elements/oneTBB/source/index.rst @@ -35,3 +35,9 @@ oneAPI Threading Building Blocks Specification mutual_exclusion.rst timing.rst info_namespace.rst + +.. toctree:: + :maxdepth: 2 + :caption: oneTBB Deprecated Interfaces: + + deprecated/task_arena_attach_tag.rst diff --git a/source/elements/oneTBB/source/task_scheduler/scheduling_controls/task_scheduler_handle_cls.rst b/source/elements/oneTBB/source/task_scheduler/scheduling_controls/task_scheduler_handle_cls.rst index d2d6a621c2..fea7e308c1 100644 --- a/source/elements/oneTBB/source/task_scheduler/scheduling_controls/task_scheduler_handle_cls.rst +++ b/source/elements/oneTBB/source/task_scheduler/scheduling_controls/task_scheduler_handle_cls.rst @@ -20,8 +20,6 @@ thread until the completion of all worker threads that were implicitly created b namespace oneapi { namespace tbb { - using attach = /* unspecified */ - class task_scheduler_handle { public: task_scheduler_handle() = default; @@ -49,7 +47,7 @@ Member Functions .. cpp:function:: task_scheduler_handle() - **Effects**: Creates an instance of the ``task_scheduler_handle`` class that does not contain any reference to the task scheduler. + **Effects**: Creates an empty instance of the ``task_scheduler_handle`` class that does not contain any reference to the task scheduler. ------------------------------------------------------- @@ -63,7 +61,7 @@ Member Functions .. cpp:function:: ~task_scheduler_handle() **Effects**: Destroys an instance of the ``task_scheduler_handle`` class. - Releases a reference to the task scheduler and deactivates an instance of the ``task_scheduler_handle`` class. + If not empty, releases a reference to the task scheduler and deactivates an instance of the ``task_scheduler_handle`` class. ------------------------------------------------------- @@ -75,31 +73,30 @@ Member Functions .. cpp:function:: task_scheduler_handle& operator=(task_scheduler_handle&& other) noexcept - **Effects**: Releases a reference to the task scheduler referenced by ``this``. Adds a reference to the task scheduler referenced by ``other``. + **Effects**: If not empty, releases a reference to the task scheduler referenced by ``this``. Adds a reference to the task scheduler referenced by ``other``. In turn, ``other`` releases its reference to the task scheduler. - -**Returns**: A reference to ``*this``. + **Returns**: A reference to ``*this``. ------------------------------------------------------- .. cpp:function:: explicit operator bool() const noexcept - **Returns**: ``true`` if ``this`` references any task scheduler; ``false`` otherwise. + **Returns**: ``true`` if ``this`` is not empty and references any task scheduler; ``false`` otherwise. ------------------------------------------------------- .. cpp:function:: void release() - **Effects**: Releases a reference to the task scheduler and deactivates an instance of the ``task_scheduler_handle`` - class. Non-blocking method. + **Effects**: If not empty, releases a reference to the task scheduler and deactivates an instance of the ``task_scheduler_handle`` + class; no effect otherwise. Non-blocking method. Non-member Functions -------------------- .. cpp:function:: void finalize(task_scheduler_handle& handle) - **Effects**: Blocks the program execution until all worker threads have been completed. Throws the ``oneapi::tbb::unsafe_wait`` - exception if it is not safe to wait for the completion of the worker threads. + **Effects**: If ``handle`` is not empty, blocks the program execution until all worker threads have been completed; no effect otherwise. + Throws the ``oneapi::tbb::unsafe_wait`` exception if it is not safe to wait for the completion of the worker threads. The following conditions should be met for finalization to succeed: @@ -124,8 +121,9 @@ If calls are performed simultaneously, more than one call might succeed. .. cpp:function:: bool finalize(task_scheduler_handle& handle, const std::nothrow_t&) noexcept - **Effects**: Blocks the program execution until all worker threads have been completed. Same as above, but returns ``true`` if all worker - threads have been completed successfully, or ``false`` if it is not safe to wait for the completion of the worker threads. + **Effects**: If ``handle`` is not empty, blocks the program execution until all worker threads have been completed; no effect otherwise. + Same as above, but returns ``true`` if all worker threads have been completed successfully, or ``false`` if it is not safe to wait for + the completion of the worker threads. Examples -------- @@ -155,4 +153,4 @@ Examples See also: -* :doc:`attach <../attach_tag_type>` \ No newline at end of file +* :doc:`attach <../attach_tag_type>` 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 73ce9394ac..a73fa6c187 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 @@ -15,8 +15,6 @@ A class that represents an explicit, user-managed task scheduler arena. namespace tbb { - using attach = /* unspecified */ - class task_arena { public: static const int automatic = /* unspecified */; @@ -26,7 +24,7 @@ A class that represents an explicit, user-managed task scheduler arena. normal = /* unspecified */, high = /* unspecified */ }; - struct attach {}; /* Deprecated (compatibility with oneTBB Specification 1.0), use oneapi::tbb::attach */ + struct constraints { numa_node_id numa_node; int max_concurrency; @@ -41,7 +39,6 @@ A class that represents an explicit, user-managed task scheduler arena. priority a_priority = priority::normal); task_arena(const task_arena &s); explicit task_arena(oneapi::tbb::attach); - explicit task_arena(task_arena::attach); /* Deprecated (compatibility with oneTBB Specification 1.0), use oneapi::tbb::attach version */ ~task_arena(); void initialize(); @@ -50,7 +47,6 @@ A class that represents an explicit, user-managed task scheduler arena. void initialize(constraints a_constraints, unsigned reserved_for_masters = 1, priority a_priority = priority::normal); void initialize(oneapi::tbb::attach); - void initialize(task_arena::attach); /* Deprecated (compatibility with oneTBB Specification 1.0), use oneapi::tbb::attach version */ void terminate(); @@ -109,14 +105,6 @@ Member types and constants When passed to a constructor or the ``initialize`` method, the initialized ``task_arena`` has a raised priority. -.. cpp:struct:: attach - - A tag for constructing a ``task_arena`` with attach. - - .. caution:: - - ``struct attach`` is deprecated (compatibility with oneTBB Specification 1.0), use oneapi::tbb::attach - .. cpp:struct:: constraints Represents limitations applied to threads within ``task_arena``. @@ -177,20 +165,6 @@ Member functions Unlike other constructors, this one automatically initializes the new ``task_arena`` when connecting to an already existing arena. -.. cpp:function:: explicit task_arena(task_arena::attach) - - Creates an instance of ``task_arena`` that is connected to the internal task arena representation currently used by the calling thread. - If no such arena exists yet, creates a ``task_arena`` with default parameters. - - .. note:: - - Unlike other constructors, this one automatically initializes - the new ``task_arena`` when connecting to an already existing arena. - - .. caution:: - - ``struct attach`` is deprecated (compatibility with oneTBB Specification 1.0), use oneapi::tbb::attach version - .. cpp:function:: ~task_arena() Destroys the ``task_arena`` instance, but the destruction may not be synchronized with any task execution inside this ``task_arena``. @@ -219,16 +193,6 @@ Member functions parameters and connects ``task_arena`` to that internal task arena representation. The method has no effect when called for an already initialized ``task_arena``. -.. cpp:function:: void initialize(task_arena::attach) - - If an internal task arena representation currently used by the calling thread, the method ignores arena - parameters and connects ``task_arena`` to that internal task arena representation. - The method has no effect when called for an already initialized ``task_arena``. - - .. caution:: - - ``struct attach`` is deprecated (compatibility with oneTBB Specification 1.0), use oneapi::tbb::attach version - .. cpp:function:: void terminate() Removes the reference to the internal task arena representation without destroying the From b7d8baa32484af04ba526622963d36744997ce45 Mon Sep 17 00:00:00 2001 From: Alex Date: Fri, 3 Sep 2021 15:22:32 +0300 Subject: [PATCH 04/13] Apply suggestions from code review Co-authored-by: Alexandra --- .../source/deprecated/task_arena_attach_tag.rst | 8 ++++---- .../oneTBB/source/task_scheduler/attach_tag_type.rst | 2 +- .../task_scheduler_handle_cls.rst | 12 ++++++------ 3 files changed, 11 insertions(+), 11 deletions(-) diff --git a/source/elements/oneTBB/source/deprecated/task_arena_attach_tag.rst b/source/elements/oneTBB/source/deprecated/task_arena_attach_tag.rst index 5fb0a6f72e..a234088187 100644 --- a/source/elements/oneTBB/source/deprecated/task_arena_attach_tag.rst +++ b/source/elements/oneTBB/source/deprecated/task_arena_attach_tag.rst @@ -1,4 +1,4 @@ -.. SPDX-FileCopyrightText: 2019-2020 Intel Corporation +.. SPDX-FileCopyrightText: 2019-2021 Intel Corporation .. .. SPDX-License-Identifier: CC-BY-4.0 @@ -9,9 +9,9 @@ task_arena::attach .. caution:: - Deprecated in oneTBB Specification 1.1 + Deprecated in oneTBB Specification 1.1. -A set of methods for constructing a task_arena with attach. +A set of methods for constructing a ``task_arena`` with ``attach``. .. code:: cpp @@ -37,7 +37,7 @@ Member types and constants .. cpp:struct:: attach - A tag for constructing a task_arena with attach. + A tag for constructing a ``task_arena`` with ``attach``. Member functions ---------------- diff --git a/source/elements/oneTBB/source/task_scheduler/attach_tag_type.rst b/source/elements/oneTBB/source/task_scheduler/attach_tag_type.rst index 52d8164f39..873d0479c6 100644 --- a/source/elements/oneTBB/source/task_scheduler/attach_tag_type.rst +++ b/source/elements/oneTBB/source/task_scheduler/attach_tag_type.rst @@ -8,7 +8,7 @@ attach tag type **[scheduler.attach]** An ``attach`` tag type is specifically used with ``task_arena`` and -``task_scheduler_handle`` interfaces. It is guaranteed to be default constructible. +``task_scheduler_handle`` interfaces. It is guaranteed to be constructible by default. .. code:: cpp diff --git a/source/elements/oneTBB/source/task_scheduler/scheduling_controls/task_scheduler_handle_cls.rst b/source/elements/oneTBB/source/task_scheduler/scheduling_controls/task_scheduler_handle_cls.rst index fea7e308c1..eeab14f371 100644 --- a/source/elements/oneTBB/source/task_scheduler/scheduling_controls/task_scheduler_handle_cls.rst +++ b/source/elements/oneTBB/source/task_scheduler/scheduling_controls/task_scheduler_handle_cls.rst @@ -7,7 +7,7 @@ task_scheduler_handle ===================== **[scheduler.task_scheduler_handle]** -The ``oneapi::tbb::task_scheduler_handle`` class and the ``oneapi::tbb::finalize`` function allow to wait for completion of worker threads. +The ``oneapi::tbb::task_scheduler_handle`` class and the ``oneapi::tbb::finalize`` function allow user to wait for completion of worker threads. When the ``oneapi::tbb::finalize`` function is called with an ``oneapi::tbb::task_scheduler_handle`` instance, it blocks the calling thread until the completion of all worker threads that were implicitly created by the library. @@ -47,7 +47,7 @@ Member Functions .. cpp:function:: task_scheduler_handle() - **Effects**: Creates an empty instance of the ``task_scheduler_handle`` class that does not contain any reference to the task scheduler. + **Effects**: Creates an empty instance of the ``task_scheduler_handle`` class that does not contain any references to the task scheduler. ------------------------------------------------------- @@ -81,7 +81,7 @@ Member Functions .. cpp:function:: explicit operator bool() const noexcept - **Returns**: ``true`` if ``this`` is not empty and references any task scheduler; ``false`` otherwise. + **Returns**: ``true`` if ``this`` is not empty and refers to some task scheduler; ``false`` otherwise. ------------------------------------------------------- @@ -100,8 +100,8 @@ Non-member Functions The following conditions should be met for finalization to succeed: -- No active (not yet terminated) instances of class ``task_arena`` exist in the whole program; -- ``task_scheduler_handle::release`` is called for each other active instance of class ``task_scheduler_handle``, possibly by different application threads. +- No active, not yet terminated, instances of ``task_arena`` class exist in the whole program. +- ``task_scheduler_handle::release`` is called for each other active instance of ``task_scheduler_handle`` class, possibly by different application threads. Under these conditions, it is guaranteed that at least one ``finalize`` call succeeds, at which point all worker threads have been completed. @@ -109,7 +109,7 @@ If calls are performed simultaneously, more than one call might succeed. .. note:: - If you know how many active ``task_scheduler_handle`` instances exist in the program, + If user knows how many active ``task_scheduler_handle`` instances exist in the program, it is necessary to ``release`` all but the last one, then call ``finalize`` for the last instance. From 011e1e470bd584819460b600e2ec36f893f13ece Mon Sep 17 00:00:00 2001 From: Alex Date: Mon, 6 Sep 2021 08:54:40 +0300 Subject: [PATCH 05/13] Update source/elements/oneTBB/source/index.rst Co-authored-by: Alexandra --- source/elements/oneTBB/source/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/elements/oneTBB/source/index.rst b/source/elements/oneTBB/source/index.rst index 61d9085829..45f0b213af 100644 --- a/source/elements/oneTBB/source/index.rst +++ b/source/elements/oneTBB/source/index.rst @@ -40,4 +40,4 @@ oneAPI Threading Building Blocks Specification :maxdepth: 2 :caption: oneTBB Deprecated Interfaces: - deprecated/task_arena_attach_tag.rst + task_arena_attach_tag.rst From d1a7f51a5552e8cb978628042d94c295d35a03d1 Mon Sep 17 00:00:00 2001 From: Alexei Katranov Date: Mon, 6 Sep 2021 08:55:20 +0300 Subject: [PATCH 06/13] Apply review remarks Signed-off-by: Alexei Katranov --- .../oneTBB/source/deprecated/task_arena_attach_tag.rst | 2 +- .../scheduling_controls/task_scheduler_handle_cls.rst | 3 +-- 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/source/elements/oneTBB/source/deprecated/task_arena_attach_tag.rst b/source/elements/oneTBB/source/deprecated/task_arena_attach_tag.rst index a234088187..363053bce9 100644 --- a/source/elements/oneTBB/source/deprecated/task_arena_attach_tag.rst +++ b/source/elements/oneTBB/source/deprecated/task_arena_attach_tag.rst @@ -49,7 +49,7 @@ Member functions .. note:: - Unlike other constructors, this one automatically initializes + Unlike other ``task_arena`` constructors, this one automatically initializes the new ``task_arena`` when connecting to an already existing arena. diff --git a/source/elements/oneTBB/source/task_scheduler/scheduling_controls/task_scheduler_handle_cls.rst b/source/elements/oneTBB/source/task_scheduler/scheduling_controls/task_scheduler_handle_cls.rst index eeab14f371..86f4776ddd 100644 --- a/source/elements/oneTBB/source/task_scheduler/scheduling_controls/task_scheduler_handle_cls.rst +++ b/source/elements/oneTBB/source/task_scheduler/scheduling_controls/task_scheduler_handle_cls.rst @@ -122,8 +122,7 @@ If calls are performed simultaneously, more than one call might succeed. .. cpp:function:: bool finalize(task_scheduler_handle& handle, const std::nothrow_t&) noexcept **Effects**: If ``handle`` is not empty, blocks the program execution until all worker threads have been completed; no effect otherwise. - Same as above, but returns ``true`` if all worker threads have been completed successfully, or ``false`` if it is not safe to wait for - the completion of the worker threads. + The behavior is the same as finalize(handle); however, ``false`` is returned instead of exception or ``true`` if no exception. Examples -------- From fcb618697a6171e1b3b83ec95c0796327e3a462c Mon Sep 17 00:00:00 2001 From: Alex Date: Tue, 7 Sep 2021 12:46:22 +0300 Subject: [PATCH 07/13] Update source/elements/oneTBB/source/index.rst --- source/elements/oneTBB/source/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/elements/oneTBB/source/index.rst b/source/elements/oneTBB/source/index.rst index 45f0b213af..61d9085829 100644 --- a/source/elements/oneTBB/source/index.rst +++ b/source/elements/oneTBB/source/index.rst @@ -40,4 +40,4 @@ oneAPI Threading Building Blocks Specification :maxdepth: 2 :caption: oneTBB Deprecated Interfaces: - task_arena_attach_tag.rst + deprecated/task_arena_attach_tag.rst From 3f51b2c77182800b233e75471885a54d4f25dc39 Mon Sep 17 00:00:00 2001 From: Alex Date: Tue, 7 Sep 2021 12:52:10 +0300 Subject: [PATCH 08/13] Apply suggestions from code review Rework otherwise text --- .../scheduling_controls/task_scheduler_handle_cls.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/elements/oneTBB/source/task_scheduler/scheduling_controls/task_scheduler_handle_cls.rst b/source/elements/oneTBB/source/task_scheduler/scheduling_controls/task_scheduler_handle_cls.rst index 86f4776ddd..877f9415e7 100644 --- a/source/elements/oneTBB/source/task_scheduler/scheduling_controls/task_scheduler_handle_cls.rst +++ b/source/elements/oneTBB/source/task_scheduler/scheduling_controls/task_scheduler_handle_cls.rst @@ -88,14 +88,14 @@ Member Functions .. cpp:function:: void release() **Effects**: If not empty, releases a reference to the task scheduler and deactivates an instance of the ``task_scheduler_handle`` - class; no effect otherwise. Non-blocking method. + class; otherwise, does nothing. Non-blocking method. Non-member Functions -------------------- .. cpp:function:: void finalize(task_scheduler_handle& handle) - **Effects**: If ``handle`` is not empty, blocks the program execution until all worker threads have been completed; no effect otherwise. + **Effects**: If ``handle`` is not empty, blocks the program execution until all worker threads have been completed; otherwise, does nothing. Throws the ``oneapi::tbb::unsafe_wait`` exception if it is not safe to wait for the completion of the worker threads. The following conditions should be met for finalization to succeed: @@ -121,7 +121,7 @@ If calls are performed simultaneously, more than one call might succeed. .. cpp:function:: bool finalize(task_scheduler_handle& handle, const std::nothrow_t&) noexcept - **Effects**: If ``handle`` is not empty, blocks the program execution until all worker threads have been completed; no effect otherwise. + **Effects**: If ``handle`` is not empty, blocks the program execution until all worker threads have been completed; otherwise, does nothing. The behavior is the same as finalize(handle); however, ``false`` is returned instead of exception or ``true`` if no exception. Examples From d25c4584f814c4c9f9142622810e3c5f9c05526b Mon Sep 17 00:00:00 2001 From: kboyarinov Date: Thu, 9 Sep 2021 12:22:38 +0300 Subject: [PATCH 09/13] Change copyright year - task_arena_attach_tag.rst --- .../elements/oneTBB/source/deprecated/task_arena_attach_tag.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/elements/oneTBB/source/deprecated/task_arena_attach_tag.rst b/source/elements/oneTBB/source/deprecated/task_arena_attach_tag.rst index 363053bce9..54cf887dd5 100644 --- a/source/elements/oneTBB/source/deprecated/task_arena_attach_tag.rst +++ b/source/elements/oneTBB/source/deprecated/task_arena_attach_tag.rst @@ -1,4 +1,4 @@ -.. SPDX-FileCopyrightText: 2019-2021 Intel Corporation +.. SPDX-FileCopyrightText: 2021 Intel Corporation .. .. SPDX-License-Identifier: CC-BY-4.0 From 091cbffee910e30e8bc7e171c3104ff6ec6753e4 Mon Sep 17 00:00:00 2001 From: kboyarinov Date: Thu, 9 Sep 2021 12:23:17 +0300 Subject: [PATCH 10/13] Change copyright - index.rst --- source/elements/oneTBB/source/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/elements/oneTBB/source/index.rst b/source/elements/oneTBB/source/index.rst index 61d9085829..c90312e807 100644 --- a/source/elements/oneTBB/source/index.rst +++ b/source/elements/oneTBB/source/index.rst @@ -1,4 +1,4 @@ -.. SPDX-FileCopyrightText: 2019-2020 Intel Corporation +.. SPDX-FileCopyrightText: 2019-2021 Intel Corporation .. .. SPDX-License-Identifier: CC-BY-4.0 From a583ae04327464f1a94c3be59ff5856685d0b5c1 Mon Sep 17 00:00:00 2001 From: "Boyarinov, Konstantin" Date: Thu, 9 Sep 2021 12:30:22 +0300 Subject: [PATCH 11/13] Add deprecated nested index page --- .../oneTBB/source/nested-depr-interfaces.rst | 12 ++++++++++++ source/elements/oneTBB/source/nested-index.rst | 1 + source/elements/oneTBB/source/task_scheduler.rst | 2 +- .../task_scheduler/task_arena/task_arena_cls.rst | 2 +- 4 files changed, 15 insertions(+), 2 deletions(-) create mode 100755 source/elements/oneTBB/source/nested-depr-interfaces.rst diff --git a/source/elements/oneTBB/source/nested-depr-interfaces.rst b/source/elements/oneTBB/source/nested-depr-interfaces.rst new file mode 100755 index 0000000000..84631ad284 --- /dev/null +++ b/source/elements/oneTBB/source/nested-depr-interfaces.rst @@ -0,0 +1,12 @@ +.. SPDX-FileCopyrightText: 2021 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +============================= + oneTBB Deprecated Interfaces +============================= + +.. toctree:: + :maxdepth: 2 + + deprecated/task_arena_attach_tag.rst diff --git a/source/elements/oneTBB/source/nested-index.rst b/source/elements/oneTBB/source/nested-index.rst index 1d794b4424..578c5cbfcd 100644 --- a/source/elements/oneTBB/source/nested-index.rst +++ b/source/elements/oneTBB/source/nested-index.rst @@ -14,3 +14,4 @@ oneTBB nested-gen-info nested-interfaces nested-aux-interfaces + nested-depr-interfaces diff --git a/source/elements/oneTBB/source/task_scheduler.rst b/source/elements/oneTBB/source/task_scheduler.rst index 9d5bd80c87..7eaa9bab5a 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 a73fa6c187..3eb4cfaa5c 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 From c9e90a7837b78263344bc82e15f447afb517b3d5 Mon Sep 17 00:00:00 2001 From: "Boyarinov, Konstantin" Date: Thu, 9 Sep 2021 12:32:01 +0300 Subject: [PATCH 12/13] Fix copyright in nested index --- source/elements/oneTBB/source/nested-index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/elements/oneTBB/source/nested-index.rst b/source/elements/oneTBB/source/nested-index.rst index 578c5cbfcd..6b0418897b 100644 --- a/source/elements/oneTBB/source/nested-index.rst +++ b/source/elements/oneTBB/source/nested-index.rst @@ -1,4 +1,4 @@ -.. SPDX-FileCopyrightText: 2019-2020 Intel Corporation +.. SPDX-FileCopyrightText: 2019-2021 Intel Corporation .. .. SPDX-License-Identifier: CC-BY-4.0 From 206614df5ceaa5325e1839310513260c16bad2d3 Mon Sep 17 00:00:00 2001 From: "Boyarinov, Konstantin" Date: Thu, 9 Sep 2021 15:29:34 +0300 Subject: [PATCH 13/13] Fix namespace indentation --- .../deprecated/task_arena_attach_tag.rst | 30 +++--- .../task_arena/task_arena_cls.rst | 92 ++++++++++--------- 2 files changed, 63 insertions(+), 59 deletions(-) diff --git a/source/elements/oneTBB/source/deprecated/task_arena_attach_tag.rst b/source/elements/oneTBB/source/deprecated/task_arena_attach_tag.rst index 54cf887dd5..0f0253aae1 100644 --- a/source/elements/oneTBB/source/deprecated/task_arena_attach_tag.rst +++ b/source/elements/oneTBB/source/deprecated/task_arena_attach_tag.rst @@ -3,7 +3,7 @@ .. SPDX-License-Identifier: CC-BY-4.0 ================== -task_arena::attach +task_arena::attach ================== **[deprecated.task_arena_attach_tag]** @@ -15,23 +15,25 @@ A set of methods for constructing a ``task_arena`` with ``attach``. .. code:: cpp - // Defined in header + // Defined in header - namespace tbb { + namespace oneapi { + namespace tbb { - class task_arena { - public: - // ... - struct attach {}; + class task_arena { + public: + // ... + struct attach {}; - explicit task_arena(task_arena::attach); - void initialize(task_arena::attach); - // ... - }; + explicit task_arena(task_arena::attach); + void initialize(task_arena::attach); + // ... + }; + + } // namespace tbb + } // namespace oneapi - } // namespace tbb - Member types and constants -------------------------- @@ -52,7 +54,7 @@ Member functions Unlike other ``task_arena`` constructors, this one automatically initializes the new ``task_arena`` when connecting to an already existing arena. - + .. cpp:function:: void initialize(task_arena::attach) If an internal task arena representation currently used by the calling thread, the method ignores 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 3eb4cfaa5c..40d1fb9722 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 @@ -11,53 +11,55 @@ A class that represents an explicit, user-managed task scheduler arena. .. code:: cpp - // Defined in header - - 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 */ + // Defined in header + + 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 */ + }; + + struct constraints { + numa_node_id numa_node; + int max_concurrency; + + constraints(numa_node_id numa_node_ = task_arena::automatic, + int max_concurrency_ = task_arena::automatic); + }; + + task_arena(int max_concurrency = automatic, unsigned reserved_for_masters = 1, + priority a_priority = priority::normal); + task_arena(constraints a_constraints, unsigned reserved_for_masters = 1, + priority a_priority = priority::normal); + task_arena(const task_arena &s); + 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(oneapi::tbb::attach); + + void terminate(); + + bool is_active() const; + int max_concurrency() const; + + template auto execute(F&& f) -> decltype(f()); + template void enqueue(F&& f); }; - struct constraints { - numa_node_id numa_node; - int max_concurrency; - - constraints(numa_node_id numa_node_ = task_arena::automatic, - int max_concurrency_ = task_arena::automatic); - }; - - task_arena(int max_concurrency = automatic, unsigned reserved_for_masters = 1, - priority a_priority = priority::normal); - task_arena(constraints a_constraints, unsigned reserved_for_masters = 1, - priority a_priority = priority::normal); - task_arena(const task_arena &s); - 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(oneapi::tbb::attach); - - void terminate(); - - bool is_active() const; - int max_concurrency() const; - - template auto execute(F&& f) -> decltype(f()); - template void enqueue(F&& f); - }; - - } // namespace tbb + } // namespace tbb + } // namespace oneapi A ``task_arena`` class represents a place where threads may share and execute tasks.