[onedpl][ranges][doc] + Range-based API description

documentation/library_guide/api_for_sycl_kernels/utility_function_object_classes.rst

@@ -2,7 +2,7 @@ Utility Function Object Classes
 ##################################
 
 The definitions of the utility function objects are available through the
-``oneapi/dpl/functional`` header.  All function objects are implemented in the ``oneapi::dpl`` namespace.
+``<oneapi/dpl/functional>`` header.  All function objects are implemented in the ``oneapi::dpl`` namespace.
 
 * ``identity``: A function object type where the operator() returns the argument unchanged.
   It is an implementation of ``std::identity`` that can be used prior to C++20.

documentation/library_guide/introduction.rst

@@ -82,12 +82,15 @@ to build the standard C++ code for execution on a SYCL device:
   icpx -fsycl -fsycl-pstl-offload=gpu program.cpp -o program
 
 This option redirects C++ parallel algorithms invoked with the ``std::execution::par_unseq`` policy
-to |onedpl_short| algorithms. It does not change the behavior of the |onedpl_short| execution policies and algorithms
-that are directly used in the code.
+to |onedpl_short| algorithms. It does not change the behavior of the |onedpl_short| algorithms and
+execution policies that are directly used in the code.
 
 Useful Information
 ==================
 
+.. _library-restrictions:
+
+
 Difference with Standard C++ Parallel Algorithms
 ************************************************
 

documentation/library_guide/kernel_templates_main.rst

@@ -10,7 +10,7 @@ It is recommended to use kernel templates when there is an opportunity to custom
 for a particular workload (for example, the number of elements and their type),
 or for a specific device (for example, based on the available local memory).
 
-To use the API, include the ``oneapi/dpl/experimental/kernel_templates`` header file.
+To use the API, include the ``<oneapi/dpl/experimental/kernel_templates>`` header file.
 The primary API namespace is ``oneapi::dpl::experimental::kt``, and nested namespaces are used to further categorize the templates.
 
 * :doc:`Kernel Configuration <kernel_templates/kernel_configuration>`. Generic structure for configuring a kernel template.

documentation/library_guide/macros.rst

@@ -27,6 +27,8 @@ Macro                             Description
 ``_PSTL_VERSION_PATCH``           ``_PSTL_VERSION % 10``: The patch number.
 ================================= ==============================
 
+.. _feature-macros:
+
 Feature Macros
 ==============
 Use these macros to test presence of specific |onedpl_short| functionality.
@@ -40,8 +42,7 @@ Macro                              Macro values and the functionality
 ---------------------------------- -----------------------------------------------
 ``ONEDPL_HAS_RANGE_ALGORITHMS``    Parallel range algorithms.
 
-                                   * ``202409L`` - for_each, transform, find, find_if, find_if_not, any_of, all_of, none_of, adjacent_find, search, search_n,
-                                     count, count_if, equal, is_sorted, sort, stable_sort, min_element, max_element, copy, copy_if, merge
+                                   * ``202409L`` - see :ref:`available algorithms <range-algorithms-202409L>`.
 ================================== ===============================================
 
 Additional Macros

documentation/library_guide/parallel_api/additional_algorithms.rst

@@ -1,7 +1,7 @@
 Additional Algorithms
 ######################
 
-The definitions of the algorithms listed below are available through the ``oneapi/dpl/algorithm``
+The definitions of the algorithms listed below are available through the ``<oneapi/dpl/algorithm>``
 header.  All algorithms are implemented in the ``oneapi::dpl`` namespace.
 
 * ``reduce_by_segment``: performs partial reductions on a sequence's values and keys. Each

documentation/library_guide/parallel_api/execution_policies.rst

@@ -4,23 +4,23 @@ Execution Policies
 According to `the oneAPI specification
 <https://uxlfoundation.github.io/oneAPI-spec/spec/elements/oneDPL/source/index.html>`_,
 |onedpl_long| (|onedpl_short|) provides execution policies semantically aligned with the C++ standard,
-also referred to as *standard aligned* or *host execution policies*, and the *device execution policies*
+referred to as *standard-aligned* or *host execution policies*, as well as *device execution policies*
 to run data parallel computations on heterogeneous systems.
 
 The execution policies are defined in the ``oneapi::dpl::execution`` namespace and provided
-in the ``oneapi/dpl/execution`` header. The policies have the following meaning:
+in the ``<oneapi/dpl/execution>`` header. The policies have the following meaning:
 
 ====================== =====================================================
-Policy Value or Type   Description
+Policy Name / Type     Description
 ====================== =====================================================
-``seq``                The standard aligned policy for sequential execution.
+``seq``                The standard-aligned policy for sequential execution.
 ---------------------- -----------------------------------------------------
-``unseq``              The standard aligned policy for unsequenced SIMD execution.
+``unseq``              The standard-aligned policy for possible unsequenced SIMD execution.
                        This policy requires user-provided functions to be SIMD-safe.
 ---------------------- -----------------------------------------------------
-``par``                The standard aligned policy for parallel execution by multiple threads.
+``par``                The standard-aligned policy for possible parallel execution by multiple threads.
 ---------------------- -----------------------------------------------------
-``par_unseq``          The standard aligned policy with the combined effect of ``unseq`` and ``par``.
+``par_unseq``          The standard-aligned policy with the combined effect of ``unseq`` and ``par``.
 ---------------------- -----------------------------------------------------
 ``device_policy``      The class template to create device policies for data parallel execution.
 ---------------------- -----------------------------------------------------
@@ -54,9 +54,9 @@ Follow these steps to add Parallel API to your application:
    - ``#include <oneapi/dpl/memory>``
 
 #. Pass a |onedpl_short| execution policy object as the first argument to a parallel algorithm
-   to specify the desired execution behavior.
+   to indicate the desired execution behavior.
 
-#. If you use the C++ standard aligned execution policies:
+#. If you use the standard-aligned execution policies:
 
    - Compile the code with options that enable OpenMP parallelism and/or SIMD vectorization pragmas.
    - Compile and link with the |onetbb_short| or |tbb_short| library for TBB-based parallelism.
@@ -197,8 +197,8 @@ The code below assumes you have added ``using namespace oneapi::dpl::execution;`
 Error Handling with Device Execution Policies
 =============================================
 
-The SYCL error handling model supports two types of errors: Synchronous errors cause the SYCL host
-runtime libraries throw exceptions. Asynchronous errors may only be processed in a user-supplied error handler
+The SYCL error handling model supports two types of errors. Synchronous errors cause the SYCL API functions
+to throw exceptions. Asynchronous errors may only be processed in a user-supplied error handler
 associated with a SYCL queue.
 
 For algorithms executed with device policies, handling all errors, synchronous or asynchronous, is a

documentation/library_guide/parallel_api/iterators.rst

@@ -1,7 +1,7 @@
 Iterators
 #########
 
-The definitions of the iterators are available through the ``oneapi/dpl/iterator``
+The definitions of the iterators are available through the ``<oneapi/dpl/iterator>``
 header.  All iterators are implemented in the ``oneapi::dpl`` namespace.
 
 * ``counting_iterator``: a random-access iterator-like type whose dereferenced value is an integer

documentation/library_guide/parallel_api/parallel_range_algorithms.rst

@@ -0,0 +1,111 @@
+Parallel Range Algorithms
+#########################
+
+C++20 introduces the `Ranges library <https://en.cppreference.com/w/cpp/ranges>`_ and
+`range algorithms <https://en.cppreference.com/w/cpp/algorithm/ranges>`_ as a modern paradigm for expressing
+generic operations on data sequences.
+
+|onedpl_long| (|onedpl_short|) extends it with *parallel range algorithms*, which can be used with the standard range
+classes to leverage |onedpl_short| ability of parallel execution on both the host computer and data parallel devices.
+
+oneDPL only supports random access ranges, because they allow simultaneous constant-time access to elements
+at any position in the range. This enables efficient workload distribution among multiple threads or processing units,
+which is essential for achieving high performance in parallel execution.
+
+.. Note::
+
+  The use of parallel range algorithms requires C++20 and the C++ standard libraries coming with GCC 10 (or higher),
+  Clang 16 (or higher) and Microsoft* Visual Studio* 2019 16.10 (or higher).
+
+Supported Range Views
+---------------------
+
+`Views <https://en.cppreference.com/w/cpp/ranges/view>`_ are lightweight ranges typically used to describe
+data transformation pipelines. The C++20 standard defines two categories of standard range views, called
+*factories* and *adaptors*:
+
+* A range factory generates its data elements on access via an index or an iterator to the range.
+* A range adaptor transforms its underlying data range(s) or view(s) into a new view with modified behavior.
+
+The following C++ standard random access adaptors and factories can be used with the |onedpl_short|
+parallel range algorithms:
+
+* ``std::ranges::views::all``: A range adaptor that returns a view that includes all elements of a range
+  (only with standard-aligned execution policies).
+* ``std::ranges::subrange``: A utility that produces a view from an iterator and a sentinel or from a range.
+* ``std::span``: A view to a contiguous data sequence. 
+* ``std::ranges::iota_view``: A range factory that generates a sequence of elements by repeatedly incrementing
+  an initial value.
+* ``std::ranges::single_view``: A view that contains exactly one element of a specified value.
+* ``std::ranges::transform_view``: A range adaptor that produces a view that applies a transformation to each element
+  of another view.
+* ``std::ranges::reverse_view``: A range adaptor that produces a reversed sequence of elements provided by another view.
+* ``std::ranges::take_view``: A range adaptor that produces a view of the first N elements from another view.
+* ``std::ranges::drop_view``: A range adaptor that produces a view excluding the first N elements from another view.
+
+Visit :doc:`pass_data_algorithms` for more information, especially on the :ref:`use of range views <use-range-views>`
+with device execution policies.
+
+Supported Algorithms
+--------------------
+
+The ``<oneapi/dpl/algorithm>`` header defines the parallel range algorithms in the ``namespace oneapi::dpl::ranges``.
+All algorithms work with both standard-aligned (host) and device execution policies.
+
+The ``ONEDPL_HAS_RANGE_ALGORITHMS`` :ref:`feature macro <feature-macros>` may be used to test for the presence of
+parallel range algorithms.
+
+.. _range-algorithms-202409L:
+
+If ``ONEDPL_HAS_RANGE_ALGORITHMS`` is defined to ``202409L`` or a greater value, the following algorithms are provided:
+
+* ``for_each``
+* ``transform``
+* ``find``
+* ``find_if``
+* ``find_if_not``
+* ``adjacent_find``
+* ``all_of``
+* ``any_of``
+* ``none_of``
+* ``search``
+* ``search_n``
+* ``count``
+* ``count_if``
+* ``equal``
+* ``sort``
+* ``stable_sort``
+* ``is_sorted``
+* ``min_element``
+* ``max_element``
+* ``copy``
+* ``copy_if``
+* ``merge``
+
+Usage Example for Parallel Range Algorithms
+-------------------------------------------
+
+.. code:: cpp
+
+    {        
+        std::vector<int> vec_in = {0, 1, 2, 3, 4, 5, 6, 7, 8, 9};
+        std::vector<int> vec_out{vec_in.size()};
+
+        auto view_in = std::ranges::views::all(vec_in) | std::ranges::views::reverse;
+        oneapi::dpl::ranges::copy(oneapi::dpl::execution::par, view_in, vec_out);
+    }
+    {
+        using usm_shared_allocator = sycl::usm_allocator<int, sycl::usm::alloc::shared>;
+        // Allocate for the queue used by the execution policy
+        usm_shared_allocator alloc{oneapi::dpl::execution::dpcpp_default.queue()};
+
+        std::vector<int, usm_shared_allocator> vec_in{{0, 1, 2, 3, 4, 5, 6, 7, 8, 9}, alloc};
+        std::vector<int, usm_shared_allocator> vec_out{vec_in.size(), alloc};
+
+        auto view_in = std::ranges::subrange(vec_in.begin(), vec_in.end()) | std::ranges::views::reverse;
+        oneapi::dpl::ranges::copy(oneapi::dpl::execution::dpcpp_default, view_in, std::span(vec_out));
+    }
+
+.. rubric:: See also:
+
+:doc:`range_based_api`