diff --git a/source/elements/oneDPL/source/parallel_api/execution_policies.rst b/source/elements/oneDPL/source/parallel_api/execution_policies.rst index e405602e2..d380d81ed 100644 --- a/source/elements/oneDPL/source/parallel_api/execution_policies.rst +++ b/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 - struct is_execution_policy; - - template - inline constexpr bool is_execution_policy_v = oneapi::dpl::execution::is_execution_policy::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 `. + Device Execution Policy +++++++++++++++++++++++ @@ -71,6 +69,7 @@ the `SYCL`_ device and queue to run oneDPL algorithms. template device_policy make_device_policy( const device_policy& = dpcpp_default ); + } } } @@ -180,5 +179,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 + + namespace oneapi { + namespace dpl { + + template + struct is_execution_policy { /*see below*/ }; + + template + constexpr bool is_execution_policy_v = oneapi::dpl::is_execution_policy::value; + + namespace execution { + + template + struct is_execution_policy { /*see below*/ }; + + template + constexpr bool is_execution_policy_v = oneapi::dpl::execution::is_execution_policy::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 in which namespace the underlying class template and its specializations +are defined. + +.. 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 writing new code, use of the type trait utilities in ``namespace oneapi::dpl`` is strongly recommended. Those + in ``namespace oneapi::dpl::execution`` are provided for backward compatibility and may be deprecated in the future. + +``is_execution_policy`` 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`` does not automatically strip references and cv-qualifiers from +its template argument. [*Note*: Use it with ``std::decay_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