Documentation for Task Group Dynamic Dependencies #1863

kboyarinov · 2025-10-01T15:33:21Z

Description

Add a comprehensive description of proposed changes

Fixes # - issue number(s) if exists

Type of change

Choose one or multiple, leave empty if none of the other choices apply

Add a respective label(s) to PR if you have permissions

bug fix - change that fixes an issue
new feature - change that adds functionality
tests - change in tests
infrastructure - change in infrastructure and CI
documentation - documentation update

Tests

added - required for new features and some bug fixes
not needed

Documentation

updated in # - add PR number
needs to be updated
not needed

Breaks backward compatibility

Yes
No
Unknown

Notify the following users

List users with @ to send notifications

Other information

vossmjp · 2025-10-03T20:54:01Z

FYI, you accidentally checked in the try_put_and_wait binary.

vossmjp · 2025-10-03T21:38:29Z

doc/main/reference/task_group_bypass_support.rst

+
+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.


It seems that task_group specification is silent on the return type of the user-provided function object. So "extends the requirements" doesn't seem right.

As far as I understand the idea of named requirement and the return type is that if the specification says nothing about the return type means that any type can be returned, but will be ignored. So "extending" the named requirement means that the implementation will react if the handle is returned.

doc/main/reference/task_group_bypass_support.rst

doc/main/reference/task_group_dynamic_dependencies.rst

vossmjp · 2025-10-03T22:17:15Z

doc/main/reference/task_group_dynamic_dependencies.rst

+
+    void run(task_handle&& handle);
+
+Schedules the task object associated with ``handle`` for execution, provided its dependencies are satisfied.


Suggested change

Schedules the task object associated with ``handle`` for execution, provided its dependencies are satisfied.

Schedules the task object associated with ``handle`` for execution when its dependencies are satisfied.

I think "when" suggests that run will schedule the task when the dependencies are satisfies. It can be interpreted as waiting for the dependencies to be satisfied and then schedule the task.
Or you believe that together with the following note the behavior is obvious?

I think the ", provided" version could be read as though the "run" function does nothing if the task object dependencies are not satisfied at the time of the call to run. But of course calling run does have an effect. It make the task available for dependency tracking, and ultimately execution once its dependencies are satisfied.

doc/main/reference/task_group_dynamic_dependencies.rst

doc/main/reference/examples/try_put_and_wait

doc/main/reference/examples/task_group_extensions_bypassing.cpp

doc/main/reference/examples/task_group_extensions_reduction.cpp

Co-authored-by: Mike Voss <[email protected]>

Co-authored-by: Alexey Kukanov <[email protected]>

doc/main/reference/task_group_dynamic_dependencies.rst

Co-authored-by: Mike Voss <[email protected]>

…neapi-src/oneTBB into dev/kboyarinov/task-group-docs

…-group-docs

akukanov · 2025-10-16T12:05:53Z

doc/main/reference/task_group_bypass_support.rst

+`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.


I think we need to say something about the returned task being effectively scheduled for execution, so it must not be explicitly submitted. This is also important because of the difference with task dependencies, where a task must be explicitly submitted (or bypassed).

I have added a note at the end of description.

doc/main/reference/task_group_bypass_support.rst

akukanov · 2025-10-16T12:14:23Z

doc/main/reference/examples/task_group_extensions_bypassing.cpp

+template <typename RandomAccessIterator, typename Function>
+void parallel_for(RandomAccessIterator begin, RandomAccessIterator end, Function f) {


Suggested change

template <typename RandomAccessIterator, typename Function>

void parallel_for(RandomAccessIterator begin, RandomAccessIterator end, Function f) {

template <typename RandomAccessIterator, typename Function>

void for_each(RandomAccessIterator begin, RandomAccessIterator end, Function f) {

Renamed to parallel_for_each since with the name for_each it is challenging to test the function because of the ambiguity with std::for_each.

akukanov · 2025-10-16T12:17:37Z

doc/main/reference/examples/task_group_extensions_bypassing.cpp

+    tbb::task_group& tg;
+}; // struct for_task
+
+// Function accepts std::iterator_traits<RandomAccessIterator>::reference argument


I do not understand this comment; it seems to be incorrect.

It was part of the original example. Removed.

doc/main/reference/examples/task_group_extensions_bypassing.cpp

doc/main/reference/task_group_dynamic_dependencies.rst

akukanov · 2025-10-16T12:36:29Z

doc/main/reference/task_group_dynamic_dependencies.rst

+.. code:: cpp
+
+    bool operator==(const task_completion_handle& t, std::nullptr_t) noexcept;
+
+*Returns*: ``true`` if ``t`` does not reference any task; otherwise, ``false``.


Maybe combine with the other operator== that only differs by the order of parameters?

akukanov · 2025-10-16T12:36:39Z

doc/main/reference/task_group_dynamic_dependencies.rst

+.. code:: cpp
+
+    bool operator!=(const task_completion_handle& t, std::nullptr_t) noexcept;
+
+Equivalent to ``!(t == nullptr)``.


doc/main/reference/task_group_dynamic_dependencies.rst

akukanov · 2025-10-16T12:46:47Z

doc/main/reference/task_group_dynamic_dependencies.rst

+.. code:: cpp
+
+    ~task_handle();
+
+Destroys the ``task_handle`` object and its associated task, if any.
+If the associated task is involved in a predecessor-successor relationship, the behavior is undefined.


For the existing API, would it make sense to take the exact description from the spec in full, the modify and highlight the differences?

I have copied the exact description from the spec and highlighted the change using admonition.
It looks like this in the rendered reference:

Co-authored-by: Alexey Kukanov <[email protected]>

Draft documentation for task_group dependencies

74a8a22

kboyarinov marked this pull request as draft October 1, 2025 15:33

kboyarinov added 10 commits October 3, 2025 14:23

Improve wording and formatting

5c1ee1c

Improve examples and formatting

5252568

Fix examples

2c83040

Fix example

c973e8e

Fix reduction example

7fc8ba2

Fix submission in reduction sample

0a8aa07

Fix returned handle check

0b81e65

Separate the documentation

8012e8a

Fix including the example

e642c63

Fix newlines at the end of file

f864a64

kboyarinov marked this pull request as ready for review October 3, 2025 14:16

kboyarinov requested review from aleksei-fedotov, dnmokhov, isaevil and vossmjp October 3, 2025 14:16

github-actions bot added the documentation label Oct 3, 2025

vossmjp reviewed Oct 3, 2025

View reviewed changes

doc/main/reference/task_group_bypass_support.rst Outdated Show resolved Hide resolved

vossmjp reviewed Oct 3, 2025

View reviewed changes

doc/main/reference/task_group_dynamic_dependencies.rst Outdated Show resolved Hide resolved

vossmjp reviewed Oct 3, 2025

View reviewed changes

doc/main/reference/task_group_dynamic_dependencies.rst Outdated Show resolved Hide resolved

vossmjp reviewed Oct 3, 2025

View reviewed changes

doc/main/reference/task_group_dynamic_dependencies.rst Outdated Show resolved Hide resolved

vossmjp reviewed Oct 3, 2025

View reviewed changes

doc/main/reference/task_group_dynamic_dependencies.rst Show resolved Hide resolved

akukanov reviewed Oct 6, 2025

View reviewed changes

doc/main/reference/examples/task_group_extensions_reduction.cpp Outdated Show resolved Hide resolved

kboyarinov and others added 2 commits October 10, 2025 13:12

Update doc/main/reference/task_group_bypass_support.rst

0a77400

Co-authored-by: Mike Voss <[email protected]>

Update doc/main/reference/task_group_dynamic_dependencies.rst

7f4d219

Co-authored-by: Mike Voss <[email protected]>

kboyarinov and others added 10 commits October 10, 2025 13:13

Update doc/main/reference/task_group_dynamic_dependencies.rst

b70a323

Co-authored-by: Mike Voss <[email protected]>

Update doc/main/reference/task_group_dynamic_dependencies.rst

f363917

Co-authored-by: Mike Voss <[email protected]>

Update doc/main/reference/task_group_dynamic_dependencies.rst

e513f87

Co-authored-by: Mike Voss <[email protected]>

Remove redundant local file

d49ae72

Update doc/main/reference/examples/task_group_extensions_bypassing.cpp

73d721a

Co-authored-by: Alexey Kukanov <[email protected]>

Update doc/main/reference/examples/task_group_extensions_reduction.cpp

63112a4

Co-authored-by: Alexey Kukanov <[email protected]>

Update doc/main/reference/examples/task_group_extensions_reduction.cpp

5f40d8e

Co-authored-by: Alexey Kukanov <[email protected]>

Apply comments to the examples

d5a0fa7

Fix bypass example

0845311

Fix typo

19d54d6

vossmjp reviewed Oct 15, 2025

View reviewed changes

doc/main/reference/task_group_dynamic_dependencies.rst Outdated Show resolved Hide resolved

kboyarinov and others added 5 commits October 16, 2025 13:15

Update doc/main/reference/task_group_dynamic_dependencies.rst

0027f75

Co-authored-by: Mike Voss <[email protected]>

Hide serial threshold for reduction example

95eac21

Merge branch 'dev/kboyarinov/task-group-docs' of https://github.com/o…

7768cac

…neapi-src/oneTBB into dev/kboyarinov/task-group-docs

Update copyrights to UXL

a3a0500

Merge remote-tracking branch 'origin/master' into dev/kboyarinov/task…

3796fb9

…-group-docs

akukanov reviewed Oct 16, 2025

View reviewed changes

kboyarinov and others added 7 commits October 16, 2025 15:55

Update doc/main/reference/task_group_bypass_support.rst

73855db

Co-authored-by: Alexey Kukanov <[email protected]>

Update doc/main/reference/examples/task_group_extensions_bypassing.cpp

59b4dc0

Co-authored-by: Alexey Kukanov <[email protected]>

Update doc/main/reference/examples/task_group_extensions_bypassing.cpp

6d8a33b

Co-authored-by: Alexey Kukanov <[email protected]>

Update doc/main/reference/task_group_dynamic_dependencies.rst

a7d90c8

Co-authored-by: Alexey Kukanov <[email protected]>

Update doc/main/reference/task_group_dynamic_dependencies.rst

3e44174

Co-authored-by: Alexey Kukanov <[email protected]>

Address review comments

33e1b16

Minor changes

3cfe4e9


		void run(task_handle&& handle);

		Schedules the task object associated with ``handle`` for execution, provided its dependencies are satisfied.

		template <typename RandomAccessIterator, typename Function>
		void parallel_for(RandomAccessIterator begin, RandomAccessIterator end, Function f) {

Documentation for Task Group Dynamic Dependencies #1863

Are you sure you want to change the base?

Documentation for Task Group Dynamic Dependencies #1863

Conversation

kboyarinov commented Oct 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Type of change

Tests

Documentation

Breaks backward compatibility

Notify the following users

Other information

Uh oh!

vossmjp commented Oct 3, 2025

Uh oh!

vossmjp Oct 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

kboyarinov commented Oct 1, 2025 •

edited

Loading

vossmjp Oct 3, 2025 •

edited

Loading