[oneDPL] Describe is_execution_policy type trait (#567)

Co-authored-by: Dan Hoeflinger <[email protected]>
Co-authored-by: Ruslan Arutyunyan <[email protected]>

Author: 3 people

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

@@ -9,8 +9,7 @@ Execution Policies
 C++ Standard Aligned Execution Policies
 +++++++++++++++++++++++++++++++++++++++
 
-oneDPL has the set of execution policies and related utilities that are semantically aligned
-with the `C++ Standard`_, 6th edition (C++20):
+oneDPL has the set of execution policies semantically aligned with the `C++ Standard`_, 6th edition (C++20):
 
 .. code:: cpp
 
@@ -30,17 +29,16 @@ with the `C++ Standard`_, 6th edition (C++20):
         inline constexpr parallel_unsequenced_policy par_unseq { /*unspecified*/ };
         inline constexpr unsequenced_policy unseq { /*unspecified*/ };
 
-        template <class T>
-        struct is_execution_policy;
-
-        template <class T>
-        inline constexpr bool is_execution_policy_v = oneapi::dpl::execution::is_execution_policy<T>::value;
       }
     }
   }
 
 See "Execution policies" in the `C++ Standard`_ for more information.
 
+.. note::
+   The ``std::is_execution_policy`` type trait resolves to ``std::false_type`` for oneDPL execution policies.
+   Implementations and programs should instead use the :ref:`oneDPL type trait <exec-policy-type-trait>`.
+
 Device Execution Policy
 +++++++++++++++++++++++
 
@@ -180,5 +178,54 @@ as the template argument, otherwise unspecified.
 Return a policy object constructed from ``policy``, with a new kernel name provided as the template
 argument. If no policy object is provided, the new policy is constructed from ``dpcpp_default``.
 
+.. _exec-policy-type-trait:
+
+Execution Policy Type Trait
++++++++++++++++++++++++++++
+
+oneDPL provides type trait utilities to detect its execution policy types at compile time for the purpose of
+function overload resolution:
+
+.. code:: cpp
+
+  // Defined in <oneapi/dpl/execution>
+
+  namespace oneapi {
+    namespace dpl {
+
+      template <class T>
+      struct is_execution_policy { /*see below*/ };
+
+      template <class T>
+      inline constexpr bool is_execution_policy_v = oneapi::dpl::is_execution_policy<T>::value;
+
+      namespace execution {
+
+        template <class T>
+        struct is_execution_policy { /*see below*/ };
+
+        template <class T>
+        inline constexpr bool is_execution_policy_v = oneapi::dpl::execution::is_execution_policy<T>::value;
+
+      }
+    }
+  }
+
+``oneapi::dpl::is_execution_policy`` and ``oneapi::dpl::execution::is_execution_policy`` must be treated
+as name aliases to the same class template. It is unspecified, which namespace contains the class template
+definition and its specializations.
+
+.. note::
+   The ``oneapi::dpl::execution::is_execution_policy`` class originated in the oneDPL specification version 1.0,
+   while ``oneapi::dpl::is_execution_policy`` has been added later to better align with the C++ standard.
+   
+   For new code, use of the type trait utilities in ``namespace oneapi::dpl`` is highly recommended. Those
+   in ``namespace oneapi::dpl::execution`` are provided for backward compatibility and may be deprecated in the future.
+
+``is_execution_policy<T>`` must have the characteristics of ``std::true_type`` if ``T`` is one of the above specified or
+implementation-defined oneDPL execution policy types, otherwise it must have the characteristics of ``std::false_type``.
+Following the C++ Standard, ``is_execution_policy<T>`` does not automatically strip references and cv-qualifiers from
+its template argument. [*Note*: Use it with ``std::decay_t<T>`` or similar type transformation utilities. -- *end note*]
+
 .. _`C++ Standard`: https://isocpp.org/std/the-standard
 .. _`SYCL`: https://registry.khronos.org/SYCL/specs/sycl-2020/html/sycl-2020.html