Skip to content

[oneTBB] Add a function to create a set of NUMA bound task arenas #650

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 15 commits into from
Oct 31, 2025
Merged

[oneTBB] Add a function to create a set of NUMA bound task arenas #650

Changes from 6 commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
f819fc1
Add a page with constraints helpers to the spec
isaevil Oct 2, 2025
6caccd4
Add newline to notion
isaevil Oct 2, 2025
b9cc94d
Apply suggestions from code review
isaevil Oct 20, 2025
43f749f
Move as non-member function into task_arena spec, update example
isaevil Oct 21, 2025
2438028
Remove constrained_arena_helpers.rst
isaevil Oct 21, 2025
532fbb4
Fix underline
isaevil Oct 21, 2025
25159ee
Apply suggestions from code review
isaevil Oct 23, 2025
94f1d5d
Fix example
isaevil Oct 23, 2025
c08478f
Move the sentence about error
isaevil Oct 23, 2025
d2be07c
Apply suggestion about arguments
isaevil Oct 23, 2025
c16ef5a
Apply suggestions from code review
isaevil Oct 24, 2025
b730cab
Clarify the parameters of task_arena in case of failed system info di…
isaevil Oct 24, 2025
52a15d7
Consistent naming of contraints and reserved_slots arguments
isaevil Oct 28, 2025
e93ac74
Update example
isaevil Oct 31, 2025
5089b5a
Improve a comment in the example
akukanov Oct 31, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 22 additions & 8 deletions source/elements/oneTBB/source/task_scheduler/task_arena/task_arena_cls.rst
View file
Open in desktop
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we have limit on the line width? Proper alignment will help avoiding unnecessary horizontal scrollings and make the rendering neater.

Consider:

Image Image

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The HTML page looks like this:
image
Seems acceptable, and I am not sure if manual line break can do better in this case.

Copy link
Contributor Author

@isaevil isaevil Oct 28, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As far as I know, you can't make indentation when using .. cpp::function with line breaks, so at best it will end up like this:

std::vector<task_arena> create_numa_task_arenas(
task_arena::constraints constraints = {}, 
int reserved_slots = 0)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We can reduce the clutter by using shorter names. For example, I find shortening of constraints function parameter to just c attractive, because:

  1. The task_arena::constraints type conveys the semantics.
  2. The description from where the parameter is referred to mentions that these are constraints.
  3. The description of the function is short enough and scoped, so c could act similarly to constructs like loop counters. Meaning, that readers are unlikely to forget what that c is about.

Similarly, the a_priority can be reduced to just p without loosing much of the readability.

This should not be overused though. For example, I would not contract the reserved_slots because its type does not convey the meaning, so the name is essential here.

Original file line number Diff line number Diff line change
Expand Up @@ -43,9 +43,9 @@ A class that represents an explicit, user-managed task scheduler arena.
};

task_arena(int max_concurrency = automatic, unsigned reserved_for_masters = 1,
priority a_priority = priority::normal);
priority a_priority = priority::normal);
task_arena(constraints a_constraints, unsigned reserved_for_masters = 1,
priority a_priority = priority::normal);
priority a_priority = priority::normal);
task_arena(const task_arena &s);
explicit task_arena(oneapi::tbb::attach);
~task_arena();
Expand All @@ -71,6 +71,9 @@ A class that represents an explicit, user-managed task scheduler arena.
task_group_status task_arena::wait_for(task_group& tg);
};

std::vector<task_arena> create_numa_task_arenas(task_arena::constraints constraints = {},
unsigned reserved_slots = 0);

} // namespace tbb
} // namespace oneapi

Expand Down Expand Up @@ -329,6 +332,22 @@ Member functions

The behavior of this function is equivalent to ``this->execute([&tg]{ return tg.wait(); })``.

Non-member Functions
--------------------

.. cpp:function:: std::vector<task_arena> create_numa_task_arenas(task_arena::constraints constraints = {}, unsigned reserved_slots = 0)

Returns a ``std::vector`` of non-initialized ``task_arena`` objects, each bound to a separate NUMA node.
The number of created ``task_arena`` is equal to the number of NUMA nodes detected on the system
which correspond to the same set of nodes returned by ``tbb::info::numa_nodes()``.
Additional ``constraints`` argument can be specified to further limit the threads joined
the ``task_arena`` objects. The ``numa_id`` value in the ``constraints`` argument is
ignored. The ``reserved_slots`` argument allows reserving specified number of slots in
``task_arena`` objects for application threads.

If error occurs during system topology parsing, returns ``std::vector`` containing single
``task_arena`` object equivalent to ``task_arena(constraints, reserved_slots)``.

Example
-------

Expand All @@ -343,14 +362,9 @@ to the corresponding NUMA node.
#include <vector>

int main() {
std::vector<oneapi::tbb::numa_node_id> numa_nodes = oneapi::tbb::info::numa_nodes();
std::vector<oneapi::tbb::task_arena> arenas(numa_nodes.size());
std::vector<oneapi::tbb::task_arena> arenas = oneapi::tbb::create_numa_task_arenas();
std::vector<oneapi::tbb::task_group> task_groups(numa_nodes.size());

for (int i = 0; i < numa_nodes.size(); i++) {
arenas[i].initialize(oneapi::tbb::task_arena::constraints(numa_nodes[i]));
}

for (int i = 0; i < numa_nodes.size(); i++) {
arenas[i].enqueue([]{
/* executed by a thread pinned to the specified NUMA node */
Expand Down
Loading