Skip to content

[oneDPL] Extend and improve the wording about parallel algorithms #657

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

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

[oneDPL] Extend and improve the wording about parallel algorithms #657

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
83a96a5
Extend and improve the wording about parallel algorithms
akukanov Oct 14, 2025
92ca9f8
Address the review feedback
akukanov Oct 15, 2025
6ca898f
Indicate the primary header for each non-standard parallel algorithm
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
4 changes: 0 additions & 4 deletions source/elements/oneDPL/source/parallel_api.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,9 +14,6 @@ All those algorithms work with *C++ Standard aligned execution policies* and wit
oneDPL also provides *parallel range algorithms*: variations of C++20 range-based algorithms
that take a oneDPL execution policy.

For all parallel algorithms (including ones with ranges) oneDPL implements list-initialization, where applicable,
as described in `P2248R8`_ proposal that is accepted for C++26.
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 think that linking to the accepted proposal is overkill here beyond mentioning the C++26 working draft? It may be more accessible currently to list the proposal.

Copy link
Contributor Author

@akukanov akukanov Oct 16, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

I follow the pattern which we already use for the parallel range API.

I think referring to the working draft (without a link) is sufficient for the key message: the API follows the path taken by the standard. I suppose that somebody who needs the details can find those out in the working draft.

I can be convinced that referring to accepted proposals provides more value - especially if this feedback comes from the users of the API/specification :)

Copy link
Contributor

Choose a reason for hiding this comment

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

I'm a bit torn. Obviously pointing to the standard draft is a little difficult to navigate if you are looking for specifics. However, it is likely the best long term option for the specification.

The paper provides easier to access details when we are talking at such a high level here without much verbosity or example etc.

I don't have a strong feeling either way, but a slight preference to including the paper with link.


Additionally, oneDPL provides wrapper functions for `SYCL`_ buffers, special iterators, and
a set of non-standard parallel algorithms.

Expand All @@ -31,4 +28,3 @@ a set of non-standard parallel algorithms.

.. _`C++ Standard`: https://isocpp.org/std/the-standard
.. _`SYCL`: https://registry.khronos.org/SYCL/specs/sycl-2020/html/sycl-2020.html
.. _`P2248R8`: https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2024/p2248r8.html
32 changes: 30 additions & 2 deletions source/elements/oneDPL/source/parallel_api/algorithms.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,11 +6,30 @@
Parallel Algorithms
-------------------

The parallel algorithms are defined in the ``<oneapi/dpl/algorithm>`` header,
in ``namespace oneapi::dpl``.
oneDPL parallel algorithms are function templates analogous to the algorithms with execution policies defined
in the `C++ Standard`_, 5th and 6th editions (C++17/20), as well as additional non-standard function templates.

oneDPL parallel algorithms reside in ``namespace oneapi::dpl``.
Standard-aligned algorithms are defined in the ``<oneapi/dpl/algorithm>``, ``<oneapi/dpl/numeric>``,
and ``<oneapi/dpl/memory>`` header files, aligned with how the `C++ Standard`_ places the respective functions
into the standard header files.

The parallel algorithms execute according to a oneDPL execution policy supplied as the first argument.

Where applicable, oneDPL supports list initialization of value parameters of the algorithms,
as in the working draft of the next C++ standard edition (C++26).

Additional Algorithms
+++++++++++++++++++++

In addition to the standard-aligned parallel algorithms, oneDPL provides the following algorithm functions.

For compatibility with the previous versions of the specification, besides their indicated header files
all these algorithms are defined in ``<oneapi/dpl/algorithm>``. [*Note*: This may be deprecated in the future. -- *end note*]

.. code:: cpp

// Defined in <oneapi/dpl/numeric>
template<typename Policy, typename InputKeyIt, typename InputValueIt,
typename OutputValueIt,
typename T = typename std::iterator_traits<InputValueIt>::value_type,
Expand Down Expand Up @@ -42,6 +61,7 @@ provided to combine the elements of the value subsequences.

.. code:: cpp

// Defined in <oneapi/dpl/numeric>
template<typename Policy, typename InputKeyIt, typename InputValueIt,
typename OutputValueIt,
typename BinaryPredcate =
Expand Down Expand Up @@ -69,6 +89,7 @@ no binary operator is provided to combine the elements of the value subsequences

.. code:: cpp

// Defined in <oneapi/dpl/numeric>
template<typename Policy, typename InputKeyIt, typename InputValueIt,
typename OutputKeyIt, typename OutputValueIt,
typename BinaryPredcate =
Expand Down Expand Up @@ -98,6 +119,7 @@ combine the values in each subsequence identified if a binary operator is not pr

.. code:: cpp

// Defined in <oneapi/dpl/algorithm>
template<typename Policy, typename InputIt1, typename InputIt2, typename OutputIt,
typename Comparator =
std::less<typename std::iterator_traits<InputIt>::value_type>>
Expand All @@ -121,6 +143,7 @@ elements ``e`` in ``[start, end)`` and a given search value ``v`` in ``[value_fi

.. code:: cpp

// Defined in <oneapi/dpl/algorithm>
template<typename Policy, typename InputIt1, typename InputIt2, typename OutputIt,
typename Comparator =
std::less<typename std::iterator_traits<InputIt>::value_type>>
Expand All @@ -143,6 +166,7 @@ The elements of ``[start, end)`` must be partitioned with respect to the compara

.. code:: cpp

// Defined in <oneapi/dpl/algorithm>
template<typename Policy, typename InputIt1, typename InputIt2, typename OutputIt,
typename Comparator =
std::less<typename std::iterator_traits<InputIt>::value_type>>
Expand All @@ -165,6 +189,7 @@ The elements of ``[start, end)`` must be partitioned with respect to the compara

.. code:: cpp

// Defined in <oneapi/dpl/algorithm>
template <typename Policy, typename InputIt, typename OutputIt, typename UnaryOp,
typename UnaryPredicate>
OutputIt
Expand Down Expand Up @@ -196,6 +221,7 @@ satisfy a given predicate, and stores the result to the output. Depending on the

.. code:: cpp

// Defined in <oneapi/dpl/algorithm>
template<typename Policy, typename KeyIt, typename ValueIt,
typename Comparator = std::less<typename std::iterator_traits<KeyIt>::value_type>>
void
Expand Down Expand Up @@ -223,6 +249,7 @@ as defined by the `C++ Standard`_.

.. code:: cpp

// Defined in <oneapi/dpl/algorithm>
template<typename Policy, typename KeyIt, typename ValueIt,
typename Comparator = std::less<typename std::iterator_traits<KeyIt>::value_type>>
void
Expand Down Expand Up @@ -250,6 +277,7 @@ as defined by the `C++ Standard`_.

.. code:: cpp

// Defined in <oneapi/dpl/numeric>
template <typename Policy, typename InputIt, typename Size, typename ValueType,
typename OutputIt>
OutputIt
Expand Down
12 changes: 6 additions & 6 deletions source/elements/oneDPL/source/parallel_api/parallel_range_api.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@ Parallel Range Algorithms
oneDPL provides variations of algorithms that work with ranges defined in the `C++ Standard`_, 6th edition (C++20)
and newer. These algorithms execute according to a oneDPL execution policy supplied as the first argument,
similarly to other oneDPL algorithms.
[*Note*: These algorithms mostly match the semantics of the parallel range algorithms in the working draft
of the next C++ standard edition (C++26). -- *end note*]

The oneDPL parallel range algorithms rely on the functionality of C++20 and are not available in the code
compiled for earlier editions of the C++ standard.
Expand All @@ -19,7 +21,7 @@ predefined function objects which static function call operators have the requir

The following differences to the standard serial C++ range algorithms apply:

- List initialization of value parameters is enabled, as in the working draft of the next C++ standard edition (C++26).
- List initialization of value parameters is enabled, as in the C++26 working draft.
- Parallel range algorithms cannot be used in constant expressions.
- The oneDPL execution policy parameter is added.
- Output data sequences are defined as ranges, not iterators.
Expand All @@ -40,9 +42,6 @@ The following differences to the standard serial C++ range algorithms apply:
`P3709R2 <https://isocpp.org/files/papers/P3709R2.html>`_.
- ``destroy`` is not marked with ``noexcept``.

[*Note*: These oneDPL algorithms mostly match the semantics of the parallel range algorithms in the C++26 working draft.
-- *end note*]

Auxiliary Definitions
+++++++++++++++++++++

Expand All @@ -53,12 +52,13 @@ of parallel range algorithms.

// C++20 analogue of std::projected_value_t; exposition only
template <typename I, typename Proj>
using /*projected-value-type*/ = std::remove_cvref_t<std::invoke_result_t<Proj&, std::iter_value_t<I>&>>;
using /*projected-value-type*/ =
std::remove_cvref_t<std::invoke_result_t<Proj&, std::iter_value_t<I>&>>;

// C++20 analogue of nothrow-random-access-range in the C++26 working draft; exposition only
// Semantic requirements are listed further below
template <typename R>
concept nothrow-random-access-range =
concept /*nothrow-random-access-range*/ =
std::ranges::random_access_range<R> &&
std::is_lvalue_reference_v<std::iter_reference_t<std::ranges::iterator_t<R>>> &&
std::same_as<std::remove_cvref_t<std::iter_reference_t<std::ranges::iterator_t<R>>>,
Expand Down
Loading