diff --git a/source/elements/oneTBB/source/task_scheduler.rst b/source/elements/oneTBB/source/task_scheduler.rst index 7eaa9bab5a..ee8abb389a 100644 --- a/source/elements/oneTBB/source/task_scheduler.rst +++ b/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 ---------- 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 0f28d54b7e..5ea898329b 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 @@ -14,17 +14,17 @@ A class that represents an explicit, user-managed task scheduler arena. // 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 */ - }; + 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 auto execute(F&& f) -> decltype(f()); + template void enqueue(F&& f); - template auto execute(F&& f) -> decltype(f()); - template 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 void task_arena::enqueue(F&& f)``), except parameter type. + + .. 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 4bde1cad1d..4c097cc7a4 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 @@ -22,10 +22,16 @@ 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) ; } } // 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 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 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 void enqueue(F&& f)``), except the parameter type. + + .. note:: + ``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 40349a8a6f..8406d60457 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,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 - void run( Func&& f ); + 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 ); + 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,6 +55,10 @@ 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``. @@ -53,18 +66,50 @@ Member functions **Requires**: Method ``wait`` must be called before destroying a ``task_group``, otherwise, the destructor throws an exception. -.. cpp:function:: template void run( Func&& f ) +.. 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 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 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 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. 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..2b4ee830dd --- /dev/null +++ b/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. \ No newline at end of file