From 83a96a5b08678abe207db1269d5429743e1e6fac Mon Sep 17 00:00:00 2001 From: Alexey Kukanov Date: Tue, 14 Oct 2025 18:20:38 +0200 Subject: [PATCH 1/7] Extend and improve the wording about parallel algorithms --- source/elements/oneDPL/source/parallel_api.rst | 4 ---- .../oneDPL/source/parallel_api/algorithms.rst | 14 +++++++++++++- .../source/parallel_api/parallel_range_api.rst | 9 ++++----- 3 files changed, 17 insertions(+), 10 deletions(-) diff --git a/source/elements/oneDPL/source/parallel_api.rst b/source/elements/oneDPL/source/parallel_api.rst index 320ffe6eed..2c49a1f01f 100644 --- a/source/elements/oneDPL/source/parallel_api.rst +++ b/source/elements/oneDPL/source/parallel_api.rst @@ -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. - Additionally, oneDPL provides wrapper functions for `SYCL`_ buffers, special iterators, and a set of non-standard parallel algorithms. @@ -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 diff --git a/source/elements/oneDPL/source/parallel_api/algorithms.rst b/source/elements/oneDPL/source/parallel_api/algorithms.rst index 6879f18352..c9bfc8f7dc 100644 --- a/source/elements/oneDPL/source/parallel_api/algorithms.rst +++ b/source/elements/oneDPL/source/parallel_api/algorithms.rst @@ -6,8 +6,20 @@ Parallel Algorithms ------------------- -The parallel algorithms are defined in the ```` header, +oneDPL parallel algorithms are defined in the ```` header, in ``namespace oneapi::dpl``. +These include functions analogous to the algorithms with execution policies defined +in the `C++ Standard`_, 5th and 6th editions (C++17/20), as well as several additional algorithms. + +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. .. code:: cpp diff --git a/source/elements/oneDPL/source/parallel_api/parallel_range_api.rst b/source/elements/oneDPL/source/parallel_api/parallel_range_api.rst index 20251dcadd..2692ba9b1b 100644 --- a/source/elements/oneDPL/source/parallel_api/parallel_range_api.rst +++ b/source/elements/oneDPL/source/parallel_api/parallel_range_api.rst @@ -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. @@ -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. @@ -40,9 +42,6 @@ The following differences to the standard serial C++ range algorithms apply: `P3709R2 `_. - ``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 +++++++++++++++++++++ @@ -58,7 +57,7 @@ of parallel range algorithms. // C++20 analogue of nothrow-random-access-range in the C++26 working draft; exposition only // Semantic requirements are listed further below template - concept nothrow-random-access-range = + concept /*nothrow-random-access-range*/ = std::ranges::random_access_range && std::is_lvalue_reference_v>> && std::same_as>>, From 92ca9f89f524209e4c1b3f6a7032a86178ab2707 Mon Sep 17 00:00:00 2001 From: Alexey Kukanov Date: Wed, 15 Oct 2025 09:16:26 +0200 Subject: [PATCH 2/7] Address the review feedback --- .../oneDPL/source/parallel_api/algorithms.rst | 14 +++++++++----- .../source/parallel_api/parallel_range_api.rst | 3 ++- 2 files changed, 11 insertions(+), 6 deletions(-) diff --git a/source/elements/oneDPL/source/parallel_api/algorithms.rst b/source/elements/oneDPL/source/parallel_api/algorithms.rst index c9bfc8f7dc..9f5ebcd903 100644 --- a/source/elements/oneDPL/source/parallel_api/algorithms.rst +++ b/source/elements/oneDPL/source/parallel_api/algorithms.rst @@ -6,10 +6,13 @@ Parallel Algorithms ------------------- -oneDPL parallel algorithms are defined in the ```` header, -in ``namespace oneapi::dpl``. -These include functions analogous to the algorithms with execution policies defined -in the `C++ Standard`_, 5th and 6th editions (C++17/20), as well as several additional algorithms. +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 ````, ````, +and ```` 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. @@ -19,7 +22,8 @@ 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. +In addition to the standard-aligned parallel algorithms, oneDPL provides the following algorithm functions, +defined in the ```` header. .. code:: cpp diff --git a/source/elements/oneDPL/source/parallel_api/parallel_range_api.rst b/source/elements/oneDPL/source/parallel_api/parallel_range_api.rst index 2692ba9b1b..3a20d4d411 100644 --- a/source/elements/oneDPL/source/parallel_api/parallel_range_api.rst +++ b/source/elements/oneDPL/source/parallel_api/parallel_range_api.rst @@ -52,7 +52,8 @@ of parallel range algorithms. // C++20 analogue of std::projected_value_t; exposition only template - using /*projected-value-type*/ = std::remove_cvref_t&>>; + using /*projected-value-type*/ = + std::remove_cvref_t&>>; // C++20 analogue of nothrow-random-access-range in the C++26 working draft; exposition only // Semantic requirements are listed further below From 6ca898f7b44a24419468d63125e2d1e2005c63c6 Mon Sep 17 00:00:00 2001 From: Alexey Kukanov Date: Thu, 16 Oct 2025 15:23:15 +0200 Subject: [PATCH 3/7] Indicate the primary header for each non-standard parallel algorithm --- .../oneDPL/source/parallel_api/algorithms.rst | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/source/elements/oneDPL/source/parallel_api/algorithms.rst b/source/elements/oneDPL/source/parallel_api/algorithms.rst index 9f5ebcd903..d1b76c9b52 100644 --- a/source/elements/oneDPL/source/parallel_api/algorithms.rst +++ b/source/elements/oneDPL/source/parallel_api/algorithms.rst @@ -22,11 +22,14 @@ 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, -defined in the ```` header. +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 ````. [*Note*: This may be deprecated in the future. -- *end note*] .. code:: cpp + // Defined in template::value_type, @@ -58,6 +61,7 @@ provided to combine the elements of the value subsequences. .. code:: cpp + // Defined in template template template::value_type>> @@ -137,6 +143,7 @@ elements ``e`` in ``[start, end)`` and a given search value ``v`` in ``[value_fi .. code:: cpp + // Defined in template::value_type>> @@ -159,6 +166,7 @@ The elements of ``[start, end)`` must be partitioned with respect to the compara .. code:: cpp + // Defined in template::value_type>> @@ -181,6 +189,7 @@ The elements of ``[start, end)`` must be partitioned with respect to the compara .. code:: cpp + // Defined in template OutputIt @@ -212,6 +221,7 @@ satisfy a given predicate, and stores the result to the output. Depending on the .. code:: cpp + // Defined in template::value_type>> void @@ -239,6 +249,7 @@ as defined by the `C++ Standard`_. .. code:: cpp + // Defined in template::value_type>> void @@ -266,6 +277,7 @@ as defined by the `C++ Standard`_. .. code:: cpp + // Defined in template OutputIt From b8ab541a99c6b3852a508c374718c49064e85138 Mon Sep 17 00:00:00 2001 From: Alexey Kukanov Date: Tue, 28 Oct 2025 14:01:28 +0100 Subject: [PATCH 4/7] Improve the wording for binary search --- .../oneDPL/source/parallel_api/algorithms.rst | 24 +++++++------------ 1 file changed, 9 insertions(+), 15 deletions(-) diff --git a/source/elements/oneDPL/source/parallel_api/algorithms.rst b/source/elements/oneDPL/source/parallel_api/algorithms.rst index d1b76c9b52..6a574bc03d 100644 --- a/source/elements/oneDPL/source/parallel_api/algorithms.rst +++ b/source/elements/oneDPL/source/parallel_api/algorithms.rst @@ -131,13 +131,11 @@ combine the values in each subsequence identified if a binary operator is not pr ``oneapi::dpl::binary_search`` performs a binary search over the data in ``[start, end)`` for each value in ``[value_first, value_last)``. If the value exists in the data searched then -the corresponding element in ``[result, result + distance(value_first, value_last))`` is set to +the corresponding element in ``[result, result + std::distance(value_first, value_last))`` is set to true, otherwise it is set to false. -If no comparator is provided, ``operator<`` is used to determine when the search value is less -than an element in the range being searched. - -The elements of ``[start, end)`` must be partitioned with respect to the comparator used. For all +The elements of ``[start, end)`` must be partitioned with respect to the comparator used, +or with respect to ``std::less`` if no comparator is provided. For all elements ``e`` in ``[start, end)`` and a given search value ``v`` in ``[value_first, value_last)``, ``comp(e, v)`` implies ``!comp(v, e)``. @@ -157,12 +155,10 @@ elements ``e`` in ``[start, end)`` and a given search value ``v`` in ``[value_fi each value in ``[value_first, value_last)`` to find the lowest index at which the search value could be inserted in ``[start, end)`` without violating the ordering defined by the comparator provided. That lowest index is then assigned to the corresponding element in -``[result, result + distance(value_first, value_last))``. - -If no comparator is provided, ``operator<`` is used to determine when the search value is less -than an element in the range being searched. +``[result, result + std::distance(value_first, value_last))``. -The elements of ``[start, end)`` must be partitioned with respect to the comparator used. +The elements of ``[start, end)`` must be partitioned with respect to the comparator used, +or with respect to ``std::less`` if no comparator is provided. .. code:: cpp @@ -180,12 +176,10 @@ The elements of ``[start, end)`` must be partitioned with respect to the compara for each value in ``[value_first, value_last)`` to find the highest index at which the search value could be inserted in ``[start, end)`` without violating the ordering defined by the comparator provided. That highest index is then assigned to the corresponding element in -``[result, result + distance(value_first, value_last))``. - -If no comparator is provided, ``operator<`` is used to determine when the search value is less -than an element in the range being searched. +``[result, result + std::distance(value_first, value_last))``. -The elements of ``[start, end)`` must be partitioned with respect to the comparator used. +The elements of ``[start, end)`` must be partitioned with respect to the comparator used, +or with respect to ``std::less`` if no comparator is provided. .. code:: cpp From 7b92b3de1274500b1f824edeedef2323a2c78d7d Mon Sep 17 00:00:00 2001 From: Alexey Kukanov Date: Tue, 28 Oct 2025 15:08:26 +0100 Subject: [PATCH 5/7] Add a link to P2248 --- source/elements/oneDPL/source/parallel_api/algorithms.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/source/elements/oneDPL/source/parallel_api/algorithms.rst b/source/elements/oneDPL/source/parallel_api/algorithms.rst index 6a574bc03d..a0f47e0dab 100644 --- a/source/elements/oneDPL/source/parallel_api/algorithms.rst +++ b/source/elements/oneDPL/source/parallel_api/algorithms.rst @@ -16,8 +16,9 @@ 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). +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 +++++++++++++++++++++ From 945928a23522b908867b14483316bc3329c8e6a3 Mon Sep 17 00:00:00 2001 From: Alexey Kukanov Date: Tue, 28 Oct 2025 16:25:38 +0100 Subject: [PATCH 6/7] Use a subheading for "Buffer Position Objects" to hide it from on-the-page TOC trees --- source/elements/oneDPL/source/parallel_api/buffer_wrappers.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/elements/oneDPL/source/parallel_api/buffer_wrappers.rst b/source/elements/oneDPL/source/parallel_api/buffer_wrappers.rst index 2baba6d646..3c97f67be3 100644 --- a/source/elements/oneDPL/source/parallel_api/buffer_wrappers.rst +++ b/source/elements/oneDPL/source/parallel_api/buffer_wrappers.rst @@ -18,7 +18,7 @@ used as iterators in other contexts, including dereference, as these types do no requirements for an iterator. Buffer Position Objects ------------------------ ++++++++++++++++++++++++ .. code:: cpp From 6741b050aeec3e31e270668b81aaee24486b3d89 Mon Sep 17 00:00:00 2001 From: Alexey Kukanov Date: Tue, 28 Oct 2025 18:27:12 +0100 Subject: [PATCH 7/7] Add a link to P3179 --- .../oneDPL/source/parallel_api/parallel_range_api.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/source/elements/oneDPL/source/parallel_api/parallel_range_api.rst b/source/elements/oneDPL/source/parallel_api/parallel_range_api.rst index 3bb83c80b8..e581af9fe6 100644 --- a/source/elements/oneDPL/source/parallel_api/parallel_range_api.rst +++ b/source/elements/oneDPL/source/parallel_api/parallel_range_api.rst @@ -8,8 +8,9 @@ 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*] +[*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.