Skip to content

Prototype a custom role for highlighting spec modifications #1879

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

Draft
akukanov wants to merge 7 commits into
base: master
Choose a base branch
from
Draft

Prototype a custom role for highlighting spec modifications #1879

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
03e0fd9
Prototype a custom role for highlighting spec modifications
akukanov Oct 16, 2025
4b02664
Fix issues. Omit highlighting of cpp:function:: for now
akukanov Oct 16, 2025
f9edc4b
Change name and color. Try .. container:: for block highlighting
akukanov Oct 16, 2025
020a1af
Use ..class:: for better formatting
akukanov Oct 16, 2025
cb5f267
Change class:: to container::
akukanov Oct 16, 2025
9187bea
Format each requirement as a section/rubric
akukanov Oct 16, 2025
6592061
Reduce the line width of the example
akukanov Oct 16, 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
31 changes: 16 additions & 15 deletions doc/main/reference/examples/rvalue_reduce.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,21 +26,22 @@
int main() {
std::vector<std::set<int>> sets;

oneapi::tbb::parallel_reduce(oneapi::tbb::blocked_range<size_t>(0, sets.size()),
std::set<int>{}, // identity element - empty set
[&](const oneapi::tbb::blocked_range<size_t>& range, std::set<int>&& value) {
for (size_t i = range.begin(); i < range.end(); ++i) {
// Having value as a non-const rvalue reference allows to efficiently
// transfer nodes from sets[i] without copying/moving the data
value.merge(std::move(sets[i]));
}
return value;
},
[&](std::set<int>&& x, std::set<int>&& y) {
x.merge(std::move(y));
return x;
}
);
oneapi::tbb::parallel_reduce(
oneapi::tbb::blocked_range<size_t>(0, sets.size()),
std::set<int>{}, // identity element - empty set
[&](const oneapi::tbb::blocked_range<size_t>& range, std::set<int>&& value) {
for (size_t i = range.begin(); i < range.end(); ++i) {
// Having value as a non-const rvalue reference allows to efficiently
// transfer nodes from sets[i] without copying/moving the data
value.merge(std::move(sets[i]));
}
return value;
},
[&](std::set<int>&& x, std::set<int>&& y) {
x.merge(std::move(y));
return x;
}
);
}
/*end_rvalue_reduce_example*/

Expand Down
61 changes: 39 additions & 22 deletions doc/main/reference/rvalue_reduce.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,50 +7,67 @@ Parallel Reduction for rvalues
:local:
:depth: 1

.. role:: specadd

.. raw:: html

<style> .specadd {background-color:palegreen;} </style>

Description
***********

|full_name| implementation extends the `ParallelReduceFunc <https://oneapi-spec.uxlfoundation.org/specifications/oneapi/latest/elements/onetbb/source/named_requirements/algorithms/par_reduce_func>`_ and
`ParallelReduceReduction <https://oneapi-spec.uxlfoundation.org/specifications/oneapi/latest/elements/onetbb/source/named_requirements/algorithms/par_reduce_reduction>`_
to optimize operating with ``rvalues`` using functional form of ``tbb::parallel_reduce`` and ``tbb::parallel_deterministic_reduce`` algorithms.

API
***
Extensions
**********

Additions to the API specifications are :specadd:`highlighted`.

.. container:: section

.. rubric:: ParallelReduceFunc Requirements: Pseudo-Signature, Semantics
:class: sectiontitle

Header
------
.. container:: specadd

.. code:: cpp
.. cpp:function:: Value Func::operator()(const Range& range, Value&& x) const

#include <oneapi/tbb/parallel_reduce.h>
or

ParallelReduceFunc Requirements: Pseudo-Signature, Semantics
------------------------------------------------------------
.. cpp:function:: Value Func::operator()(const Range& range, const Value& x) const

.. cpp:function:: Value Func::operator()(const Range& range, Value&& x) const
Accumulates the result for a subrange, starting with initial value ``x``.
The ``Range`` type must meet the
`Range requirements <https://oneapi-spec.uxlfoundation.org/specifications/oneapi/latest/elements/onetbb/source/named_requirements/algorithms/range>`_.
The ``Value`` type must be the same as a corresponding template parameter for the
`parallel_reduce algorithm <https://oneapi-spec.uxlfoundation.org/specifications/oneapi/latest/elements/onetbb/source/algorithms/functions/parallel_reduce_func>`_.

or
.. container:: specadd

If both ``rvalue`` and ``lvalue`` forms are provided, the ``rvalue`` is preferred.

.. cpp:function:: Value Func::operator()(const Range& range, const Value& x) const
.. container:: section

Accumulates the result for a subrange, starting with initial value ``x``. The ``Range`` type must meet the
`Range requirements <https://oneapi-spec.uxlfoundation.org/specifications/oneapi/latest/elements/onetbb/source/named_requirements/algorithms/range>`_.
The ``Value`` type must be the same as a corresponding template parameter for the `parallel_reduce algorithm <https://oneapi-spec.uxlfoundation.org/specifications/oneapi/latest/elements/onetbb/source/algorithms/functions/parallel_reduce_func>`_.
.. rubric:: ParallelReduceReduction Requirements: Pseudo-Signature, Semantics
:class: sectiontitle

If both ``rvalue`` and ``lvalue`` forms are provided, the ``rvalue`` is preferred.
.. container:: specadd

ParallelReduceReduction Requirements: Pseudo-Signature, Semantics
-----------------------------------------------------------------
.. cpp:function:: Value Reduction::operator()(Value&& x, Value&& y) const

.. cpp:function:: Value Reduction::operator()(Value&& x, Value&& y) const
or

or
.. cpp:function:: Value Reduction::operator()(const Value& x, const Value& y) const

.. cpp:function:: Value Reduction::operator()(const Value& x, const Value& y) const
Combines the ``x`` and ``y`` results.
The ``Value`` type must be the same as a corresponding template parameter for the
`parallel_reduce algorithm <https://oneapi-spec.uxlfoundation.org/specifications/oneapi/latest/elements/onetbb/source/algorithms/functions/parallel_reduce_func>`_.

Combines the ``x`` and ``y`` results. The ``Value`` type must be the same as a corresponding template parameter for the `parallel_reduce algorithm <https://oneapi-spec.uxlfoundation.org/specifications/oneapi/latest/elements/onetbb/source/algorithms/functions/parallel_reduce_func>`_.
.. container:: specadd

If both ``rvalue`` and ``lvalue`` forms are provided, the ``rvalue`` is preferred.
If both ``rvalue`` and ``lvalue`` forms are provided, the ``rvalue`` is preferred.

Example
*******
Expand Down