[oneDPL] Indirectly Device Accessible Iterator Customization Point and Public Trait

source/elements/oneDPL/source/parallel_api/execution_policies.rst

@@ -99,7 +99,11 @@ to run algorithms on a SYCL device. When an algorithm runs with ``device_policy`
 it is capable of processing SYCL buffers (passed via ``oneapi::dpl::begin/end``),
 data in the host memory and data in Unified Shared Memory (USM), including device USM.
 Data placed in the host memory and USM can be passed to oneDPL algorithms
-as pointers and random access iterators. The way to transfer data from the host memory
+as pointers and random access iterators. oneDPL provides some :ref:`iterators <iterators>` that are
+compatible with algorithms when using a ``device_policy``. Custom iterators may also be used, but users should
+ensure that those iterators have a defined :ref:`"passed directly" customization point <iterators-passed-directly>`
+to avoid unnecessary data movement. The iterators must also be SYCL device-copyable to be used with
+algorithms utilizing a ``device_policy``. The way to transfer data from the host memory
 to a device and back is unspecified; per-element data movement to/from a temporary storage
 is a possible valid implementation.
 

source/elements/oneDPL/source/parallel_api/iterators.rst

@@ -3,6 +3,8 @@
 ..
 .. SPDX-License-Identifier: CC-BY-4.0
 
+.. _iterators:
+
 Iterators
 ---------
 
@@ -301,3 +303,109 @@ operation were applied to each of these iterators. The types ``T`` within the te
 
 ``make_zip_iterator`` constructs and returns an instance of ``zip_iterator``
 using the set of source iterators provided.
+
+.. _iterators-passed-directly:
+
+Customization Point for "Passed Directly" Iterators
+---------------------------------------------------
+
+Iterator types can be "passed directly" to `SYCL`_ kernels when they can inherently be dereferenced on the device while
+using an algorithm with a ``device_policy``. Examples of iterators which can be "passed directly" include SYCL USM
+shared or device memory, or iterator types like ``counting_iterator`` or ``discard_iterator`` that do not require any
+data to be copied to the device. An example of an iterator type that cannot be "passed directly" is a ``std::vector``
+iterator, which requires the data to be copied to the device in some way prior to usage in a SYCL kernel within
+algorithms used with a ``device_policy``.
+
+oneDPL provides a mechanism to define whether custom iterator types can be "passed directly" to SYCL kernels.  oneDPL
+queries this information at compile time to determine how to handle the iterator type when passed to algorithms with a
+``device_policy``. This is important because it allows oneDPL to avoid unnecessary data movement. This is achieved using
+the ``is_passed_directly_in_onedpl_device_policies`` Argument-Dependent Lookup (ADL) customization point and the public
+trait ``is_passed_directly_to_device[_v]``.
+
+ADL Customization Point: ``is_passed_directly_in_onedpl_device_policies``
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+A free function ``is_passed_directly_in_onedpl_device_policies(IteratorT)`` may be defined, which accepts an argument
+of type ``IteratorT`` and returns a type with the characteristics of ``std::true_type`` if ``IteratorT`` can be
+"passed directly" to SYCL kernels, or alternatively returns a type with the characteristics of ``std::false_type``
+otherwise. The function must be defined in one of the valid search locations for ADL lookup, which includes the
+namespace of the definition of the iterator type ``IteratorT``.
+
+The function ``is_passed_directly_in_onedpl_device_policies`` may be used by oneDPL to determine whether the iterator
+type can be "passed directly" to SYCL kernels by interrogating its return type at compile time only. It shall not be
+called by oneDPL outside a ``decltype`` context to determine the return type. This means that overloads may be provided
+as forward declarations only, without a body defined. ADL lookup is used to determine which function overload to use
+according to the rules in the `C++ Standard`_. Therefore, derived iterator types without an overload for their exact
+type will match their most specific base iterator type if such an overload exists.
+
+The default implementation of ``is_passed_directly_in_onedpl_device_policies`` marks the following iterators as
+"passed directly":
+* Pointers (to handle USM pointers)
+* Iterators with the ``using is_passed_directly = std::true_type`` trait
+* Iterators to USM shared allocated ``std::vector``-s when the allocator type is knowable from the iterator type
+* ``std::reverse_iterator<IteratorT>`` when ``IteratorT`` is "passed directly"
+
+oneDPL defines the "passed directly" behavior for its custom iterators as follows:
+* ``counting_iterator`` and ``discard_iterator``: Always "passed directly".
+* ``permutation_iterator``: "Passed directly" if both its source iterator and its index map are "passed directly".
+* ``transform_iterator``: "Passed directly" if its source iterator is "passed directly".
+* ``zip_iterator``: "Passed directly" if all base iterators are "passed directly".
+
+
+Public Trait: ``is_passed_directly_to_device[_v]``
+++++++++++++++++++++++++++++++++++++++++++++++++++
+
+The public trait ``oneapi::dpl::is_passed_directly_to_device[_v]`` can be used to query whether an iterator type is
+"passed directly" to SYCL kernels. The trait is defined in ``<oneapi/dpl/iterator>``.
+
+``oneapi::dpl::is_passed_directly_to_device<T>`` evaluates to a type with the characteristics of ``std::true_type`` if
+``T`` can be "passed directly" to SYCL kernels, otherwise it evaluates to a type with the characteristics of
+``std::false_type``.
+
+``oneapi::dpl::is_passed_directly_to_device_v<T>`` is a ``constexpr bool`` that evaluates to ``true`` if ``T`` can be
+"passed directly" to SYCL kernels, otherwise it evaluates to ``false``.
+
+Example
++++++++
+
+.. code:: cpp
+
+    namespace usr
+    {
+        struct pass_dir_it
+        {
+        /* unspecified user definition of a "passed directly" iterator */
+        };
+
+        std::true_type
+        is_passed_directly_in_onedpl_device_policies(pass_dir_it);
+
+        struct no_pass_dir_it
+        {
+            /* unspecified user definition of a non "passed directly" iterator */
+        };
+
+        std::false_type
+        is_passed_directly_in_onedpl_device_policies(no_pass_dir_it);
+    }
+
+    static_assert(oneapi::dpl::is_passed_directly_to_device_v<usr::pass_dir_it> == true);
+    static_assert(oneapi::dpl::is_passed_directly_to_device_v<usr::no_pass_dir_it> == false);
+
+    // Example with base iterators and ADL overload as a hidden friend
+    template <typename It1, typename It2>
+    struct it_pair
+    {
+        It1 first;
+        It2 second;
+        friend auto is_passed_directly_in_onedpl_device_policies(it_pair) ->
+            std::conjunction<oneapi::dpl::is_passed_directly_to_device<It1>,
+                             oneapi::dpl::is_passed_directly_to_device<It2>>;
+    };
+
+    static_assert(oneapi::dpl::is_passed_directly_to_device_v<it_pair<usr::pass_dir_it, usr::pass_dir_it>> == true);
+    static_assert(oneapi::dpl::is_passed_directly_to_device_v<it_pair<usr::pass_dir_it, usr::no_pass_dir_it>> == false);
+
+
+.. _`C++ Standard`: https://isocpp.org/std/the-standard
+.. _`SYCL`: https://registry.khronos.org/SYCL/specs/sycl-2020/html/sycl-2020.html