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

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

@@ -99,9 +99,9 @@ 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
-to a device and back is unspecified; per-element data movement to/from a temporary storage
-is a possible valid implementation.
+as pointers and random access iterators, including :doc:`oneDPL iterators <iterators>`. 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.
 
 The ``KernelName`` template parameter, also aliased as ``kernel_name`` within the class template,
 is to explicitly provide a name for SYCL kernels executed by an algorithm the policy is passed to.

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

@@ -3,9 +3,31 @@
 ..
 .. SPDX-License-Identifier: CC-BY-4.0
 
+.. _iterators:
+
 Iterators
 ---------
 
+Requirements For Iterator Use With Device Policies
+++++++++++++++++++++++++++++++++++++++++++++++++++
+Iterator are, by default, not assumed to refer to content which is accessible on the device which requires the content
+to be copied to the device prior to being used inside a `SYCL`_ kernel. We define iterators to be "device accessible
+content iterators" when they can inherently be dereferenced on the device in a SYCL kernel. When using oneDPL algorithms
+with a ``device_policy``, "device accessible content iterators" avoid unnecessary data movement when provided as input
+or output arguments.
+
+Examples of "device accessible content iterators" 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 to be used in a
+SYCL kernel. An example of an iterator which does not refer to "device accessible content" 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``.
+
+When used as input or output with algorithms using a ``device_policy`` "device accessible content iterators" must also
+be SYCL device-copyable, as defined by the SYCL Specification.
+
+oneDPL Iterators
+++++++++++++++++
+
 The oneDPL iterators are defined in the ``<oneapi/dpl/iterator>`` header,
 in ``namespace oneapi::dpl``.
 
@@ -64,6 +86,8 @@ counter; dereference operations cannot be used to modify the counter. The arithm
 operators of ``counting_iterator`` behave as if applied to the values of Integral type
 representing the counters of the iterator instances passed to the operators.
 
+``counting_iterator`` are always SYCL device-copyable, and are always "device accessible content iterators".
+
 .. code:: cpp
 
     class discard_iterator
@@ -104,6 +128,8 @@ lvalue that may be assigned an arbitrary value. The assignment has no effect on
 of ``discard_iterator`` behave as if applied to integer counter values maintained by the
 iterator instances to determine their position relative to each other.
 
+``discard_iterator`` are always SYCL device-copyable, and are always "device accessible content iterators".
+
 .. code:: cpp
 
     template <typename SourceIterator, typename IndexMap>
@@ -174,6 +200,10 @@ to index into the index map. The corresponding value in the map is then used
 to index into the value set defined by the source iterator. The resulting lvalue is returned
 as the result of the operator.
 
+``permutation_iterator`` are SYCL device-copyable if both the ``SourceIterator`` and the ``IndexMap``
+are SYCL device-copyable, and are always "device accessible content iterators" if both the ``SourceIterator``
+and the ``IndexMap`` are "device accessible content iterators".
+
 .. code:: cpp
 
     template <typename SourceIterator, typename IndexMap>
@@ -234,6 +264,10 @@ arithmetic and comparison operators of ``transform_iterator`` behave as if appli
 source iterator itself. The template type ``Iterator`` must satisfy
 ``AdaptingIteratorSource``.
 
+``transform_iterator`` is SYCL device-copyable if the source iterator is SYCL device-copyable, and
+is always "device accessible content iterator" if the source iterator is a "device accessible
+content iterator".
+
 .. code:: cpp
 
     template <typename UnaryFunc, typename Iterator>
@@ -293,6 +327,10 @@ source iterators over which the ``zip_iterator`` is defined. The arithmetic oper
 operation were applied to each of these iterators. The types ``T`` within the template pack 
 ``Iterators...`` must satisfy ``AdaptingIteratorSource``.
 
+``zip_iterator`` is SYCL device-copyable if all the source iterators are SYCL device-copyable, and
+is always "device accessible content iterator" if all the source iterators are "device accessible
+content iterators".
+
 .. code:: cpp
 
     template <typename... Iterators>
@@ -301,3 +339,105 @@ 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-device-accessible:
+
+Customization For User Defined Iterators
+++++++++++++++++++++++++++++++++++++++++
+
+oneDPL provides a mechanism to indicate whether custom iterators are "device accessible content iterators" by defining
+an Argument-Dependent Lookup (ADL) customization point, ``is_onedpl_device_accessible_content_iterator``. oneDPL also
+defines a public trait, ``is_device_accessible_content_iterator[_v]`` to indicate whether an iterator is a "device
+accessible content iterator".
+
+oneDPL queries this information at compile time to determine how to handle iterator types when they are passed to
+algorithms with a ``device_policy`` to avoid unnecessary data movement.
+
+ADL Customization Point: ``is_onedpl_device_accessible_content_iterator``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A free function ``is_onedpl_device_accessible_content_iterator(IteratorT)`` may be defined, which accepts an argument
+of type ``IteratorT`` and returns a type with the characteristics of ``std::true_type`` if ``IteratorT`` refers to
+"device accessible content", 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_onedpl_device_accessible_content_iterator`` may be used by oneDPL to determine if the iterator refers
+to "device accessible content" 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. 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_onedpl_device_accessible_content_iterator`` marks the following iterators as to
+"device accessible content iterators":
+* Pointers (to handle USM pointers)
+* Iterators to USM shared allocated ``std::vector``-s when the allocator type is knowable from the iterator type
+* ``std::reverse_iterator<IteratorT>`` when ``IteratorT`` refers to "device accessible content"
+
+
+
+Public Trait: ``oneapi::dpl::is_device_accessible_content_iterator[_v]``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The public trait ``oneapi::dpl::is_device_accessible_content_iterator[_v]`` can be used to query whether an iterator
+is a "device accessible content iterator". The trait is defined in ``<oneapi/dpl/iterator>``.
+
+``oneapi::dpl::is_device_accessible_content_iterator<T>`` evaluates to a type with the characteristics of
+``std::true_type`` if ``T``  refers to "device accessible content", otherwise it evaluates to a type with the
+characteristics of ``std::false_type``.
+
+``oneapi::dpl::is_device_accessible_content_iterator<T>`` is a ``constexpr bool`` that evaluates to ``true`` if ``T``
+refers to "device accessible content", otherwise it evaluates to ``false``.
+
+
+
+
+Example
+^^^^^^^
+
+The following example shows how to define a ADL overload for a simple user defined iterator.  It also shows an example
+for a more complicated case which uses a hidden friend to provide the ADL overload within the definition of the
+iterator.
+
+.. code:: cpp
+
+    namespace usr
+    {
+        struct accessible_it
+        {
+        /* unspecified user definition of a iterator which refers to "device accessible content" */
+        };
+
+        std::true_type
+        is_onedpl_device_accessible_content_iterator(accessible_it);
+
+        struct inaccessible_it
+        {
+            /* unspecified user definition of iterator which doesn't refer to "device accessible content" */
+        };
+
+        // This could be omitted. It would rely upon the default implementation with the same result
+        std::false_type
+        is_onedpl_device_accessible_content_iterator(inaccessible_it);
+    }
+
+    static_assert(oneapi::dpl::is_device_accessible_content_iterator<usr::accessible_it> == true);
+    static_assert(oneapi::dpl::is_device_accessible_content_iterator<usr::inaccessible_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_onedpl_device_accessible_content_iterator(it_pair) ->
+            std::conjunction<oneapi::dpl::is_device_accessible_content_iterator<It1>,
+                             oneapi::dpl::is_device_accessible_content_iterator<It2>>;
+    };
+
+    static_assert(oneapi::dpl::is_device_accessible_content_iterator<it_pair<usr::accessible_it, usr::accessible_it>> == true);
+    static_assert(oneapi::dpl::is_device_accessible_content_iterator<it_pair<usr::accessible_it, usr::inaccessible_it>> == false);
+
+.. _`C++ Standard`: https://isocpp.org/std/the-standard
+.. _`SYCL`: https://registry.khronos.org/SYCL/specs/sycl-2020/html/sycl-2020.html