Documentation for Task Group Dynamic Dependencies (#1863)

Co-authored-by: Mike Voss <[email protected]>
Co-authored-by: Alexey Kukanov <[email protected]>
Co-authored-by: Ilya Isaev <[email protected]>

Author: 4 people

doc/main/reference/examples/task_group_extensions_bypassing.cpp

@@ -0,0 +1,80 @@
+/*
+    Copyright (c) 2025 UXL Foundation Contributors
+
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+*/
+
+#include <cstdint>
+#include <vector>
+#include <iostream>
+
+static constexpr std::size_t serial_threshold = 16;
+
+/*begin_task_group_extensions_bypassing_example*/
+#define TBB_PREVIEW_TASK_GROUP_EXTENSIONS 1
+#include "oneapi/tbb/task_group.h"
+
+template <typename Iterator, typename Function>
+struct for_task {
+    tbb::task_handle operator()() const {
+        tbb::task_handle next_task;
+
+        auto size = end - begin;
+        if (size < serial_threshold) {
+            // Execute the work serially
+            for (Iterator it = begin; it != end; ++it) {
+                f(*it);
+            }
+        } else {
+            // Enough work to split the range
+            Iterator middle = begin + size / 2;
+
+            // Submit the right subtask for execution
+            tg.run(for_task<Iterator, Function>{middle, end, f, tg});
+
+            // Bypass the left subtask
+            next_task = tg.defer(for_task<Iterator, Function>{begin, middle, f, tg});
+        }
+        return next_task;
+    }
+
+    Iterator begin;
+    Iterator end;
+    Function f;
+    tbb::task_group& tg;
+}; // struct for_task
+
+template <typename RandomAccessIterator, typename Function>
+void par_for_each(RandomAccessIterator begin, RandomAccessIterator end, Function f) {
+    tbb::task_group tg;
+    // Run the root task
+    tg.run_and_wait(for_task<RandomAccessIterator, Function>{begin, end, std::move(f), tg});
+}
+/*end_task_group_extensions_bypassing_example*/
+
+int main() {
+    constexpr std::size_t N = 1000;
+
+    std::size_t array[N];
+
+    par_for_each(array, array + N, [](std::size_t& item) {
+        item = 42;
+    });
+
+    for (std::size_t i = 0; i < N; ++i) {
+        if (array[i] != 42) {
+            std::cerr << "Error in " << i << "index" << std::endl;
+            return 1;
+        }
+    }
+}

doc/main/reference/examples/task_group_extensions_reduction.cpp

@@ -0,0 +1,98 @@
+/*
+    Copyright (c) 2025 UXL Foundation Contributors
+
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+*/
+
+#include <cstdint>
+#include <iostream>
+
+static constexpr std::size_t serial_threshold = 16;
+
+/*begin_task_group_extensions_reduction_example*/
+#define TBB_PREVIEW_TASK_GROUP_EXTENSIONS 1
+#include "oneapi/tbb/task_group.h"
+
+struct reduce_task {
+
+    struct join_task {
+        void operator()() const {
+            result = *left + *right;
+        }
+
+        std::size_t& result;
+        std::unique_ptr<std::size_t> left;
+        std::unique_ptr<std::size_t> right;
+    };
+
+    tbb::task_handle operator()() const {
+        tbb::task_handle next_task;
+
+        std::size_t size = end - begin;
+        if (size < serial_threshold) {
+            // Perform serial reduction
+            for (std::size_t i = begin; i < end; ++i) {
+                result += i;
+            }
+        } else {
+            // The range is too large to process directly
+            // Divide it into smaller segments for parallel execution
+            std::size_t middle = begin + size / 2;
+
+            auto left_result = std::make_unique<std::size_t>(0);
+            auto right_result = std::make_unique<std::size_t>(0);
+
+            
+            tbb::task_handle left_leaf = tg.defer(reduce_task{begin, middle, *left_result, tg});
+            tbb::task_handle right_leaf = tg.defer(reduce_task{middle, end, *right_result, tg});
+
+            tbb::task_handle join = tg.defer(join_task{result, std::move(left_result), std::move(right_result)});
+
+            tbb::task_group::set_task_order(left_leaf, join);
+            tbb::task_group::set_task_order(right_leaf, join);
+
+            tbb::task_group::transfer_this_task_completion_to(join);
+
+            // Save the left leaf for further bypassing
+            next_task = std::move(left_leaf);
+
+            tg.run(std::move(right_leaf));
+            tg.run(std::move(join));
+        }
+
+        return next_task;
+    }
+
+    std::size_t begin;
+    std::size_t end;
+    std::size_t& result;
+    tbb::task_group& tg;
+};
+
+std::size_t calculate_parallel_sum(std::size_t begin, std::size_t end) {
+    tbb::task_group tg;
+
+    std::size_t reduce_result = 0;
+    tg.run_and_wait(reduce_task{begin, end, reduce_result, tg});
+
+    return reduce_result;
+}
+/*end_task_group_extensions_reduction_example*/
+
+int main() {
+    constexpr std::size_t N = 10000;
+    std::size_t serial_sum = N * (N - 1) / 2;
+    std::size_t parallel_sum = calculate_parallel_sum(0, N);
+
+    if (serial_sum != parallel_sum) std::cerr << "Incorrect reduction result" << std::endl;
+}

doc/main/reference/task_group_bypass_support.rst

@@ -0,0 +1,100 @@
+.. _task_group_bypass_support:
+
+Task Bypass Support for ``task_group``
+======================================
+
+.. note::
+    To enable this extension, define the ``TBB_PREVIEW_TASK_GROUP_EXTENSIONS`` macro with a value of ``1``.
+
+.. contents::
+    :local:
+    :depth: 2
+
+Description
+***********
+
+The |full_name| implementation extends the requirements for user-provided function object from
+`tbb::task_group specification <https://oneapi-spec.uxlfoundation.org/specifications/oneapi/latest/elements/onetbb/source/task_scheduler/task_group/task_group_cls>`_
+to allow them to return a ``task_handle`` object.
+
+`Task Bypassing <../tbb_userguide/Task_Scheduler_Bypass.html>`_ allows developers to reduce task scheduling overhead by providing a hint about
+which task should be executed next.
+
+Execution of the deferred task owned by a returned ``task_handle`` is not guaranteed to occur immediately, nor to be performed by the same thread.
+
+.. code:: cpp
+
+    tbb::task_handle task_body() {
+        tbb::task_handle next_task = group.defer(next_task_body);
+        return next_task;
+    }
+
+API
+***
+
+Header
+------
+
+.. code:: cpp
+
+    #define TBB_PREVIEW_TASK_GROUP_EXTENSIONS 1
+    #include <oneapi/tbb/task_group.h>
+
+Synopsis
+--------
+
+.. code:: cpp
+
+    namespace oneapi {
+        namespace tbb {
+            class task_group {
+            public:
+                // Only the requirements for the return type of function F are changed
+                template <typename F>
+                task_handle defer(F&& f);
+
+                // 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);
+            }; // class task_group
+        } // namespace tbb
+    } // namespace oneapi
+
+Member Functions
+----------------
+
+.. code:: cpp
+
+    template <typename F>
+    task_handle defer(F&& f);
+
+    template <typename F>
+    task_group_status run_and_wait(const F& f);
+
+    template <typename F>
+    void run(F&& f);
+
+The ``F`` type must meet the *Function Objects* requirements described in the [function.objects] section of the ISO C++ Standard.
+
+.. admonition:: Extension
+
+    ``F`` may return a ``task_handle`` object. If the returned handle is non-empty and owns a task without dependencies, it serves as an optimization hint
+    for a task that could be executed next.
+
+    The returned ``task_handle`` must not be explicitly submitted with ``task_group::run`` or another submission function, otherwise, the behavior is undefined.
+
+    If the returned handle was created by a ``task_group`` other than ``*this``, the behavior is undefined.     
+
+Example
+-------
+
+The example below demonstrates how to process a sequence in parallel using ``task_group`` and the divide-and-conquer pattern.
+
+.. literalinclude:: ./examples/task_group_extensions_bypassing.cpp
+    :language: c++
+    :start-after: /*begin_task_group_extensions_bypassing_example*/
+    :end-before: /*end_task_group_extensions_bypassing_example*/