From ff342a7e945d1eb69c2e1eebbc281b4ce60eafb4 Mon Sep 17 00:00:00 2001 From: Alexey Kukanov Date: Tue, 20 Aug 2024 15:10:08 +0200 Subject: [PATCH 1/9] Create a subsection for is_execution_policy type trait --- .../parallel_api/execution_policies.rst | 60 ++++++++++++++++--- 1 file changed, 53 insertions(+), 7 deletions(-) diff --git a/source/elements/oneDPL/source/parallel_api/execution_policies.rst b/source/elements/oneDPL/source/parallel_api/execution_policies.rst index e405602e2..b7ca9fc10 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 `oneDPL type trait `_. + Device Execution Policy +++++++++++++++++++++++ @@ -180,5 +178,53 @@ 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``. +Execution Policy Type Trait ++++++++++++++++++++++++++++ + +oneDPL provides type trait utilities to detect at compile time its execution policy types for the purpose of +function overload resolution: + +.. code:: cpp + + // Defined in + + namespace oneapi { + namespace dpl { + + namespace execution { + + template + struct is_execution_policy { /*see below*/ }; + + template + inline constexpr bool is_execution_policy_v = oneapi::dpl::execution::is_execution_policy::value; + + } + + template + struct is_execution_policy { /*see below*/ }; + + template + inline constexpr bool is_execution_policy_v = oneapi::dpl::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. + +``is_execution_policy`` must have the characteristics of ``std::true_type`` if ``T`` is one of the above specified +or implementation-defined 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 and should be used with ``std::decay`` or similar type transformation utilities. + +.. 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 strongly recommended. + Those in ``namespace oneapi::dpl::execution`` are provided for backward compatibility and might get deprecated. + .. _`C++ Standard`: https://isocpp.org/std/the-standard .. _`SYCL`: https://registry.khronos.org/SYCL/specs/sycl-2020/html/sycl-2020.html From d8f05ebcc8a819ef3031172e90257f178c73f3f2 Mon Sep 17 00:00:00 2001 From: Alexey Kukanov Date: Tue, 20 Aug 2024 16:37:47 +0200 Subject: [PATCH 2/9] Use :ref: for internal subsection reference --- .../oneDPL/source/parallel_api/execution_policies.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/source/elements/oneDPL/source/parallel_api/execution_policies.rst b/source/elements/oneDPL/source/parallel_api/execution_policies.rst index b7ca9fc10..299f046e6 100644 --- a/source/elements/oneDPL/source/parallel_api/execution_policies.rst +++ b/source/elements/oneDPL/source/parallel_api/execution_policies.rst @@ -37,7 +37,7 @@ 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 `oneDPL type trait `_. + Implementations and programs should instead use the :ref:`oneDPL type trait `_. Device Execution Policy +++++++++++++++++++++++ @@ -178,6 +178,8 @@ 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 +++++++++++++++++++++++++++ From fa0f037a2abdadec06bcf9baa611452ab05b6ba4 Mon Sep 17 00:00:00 2001 From: Alexey Kukanov Date: Tue, 20 Aug 2024 16:44:47 +0200 Subject: [PATCH 3/9] Apply the review suggestion Co-authored-by: Dan Hoeflinger --- .../oneDPL/source/parallel_api/execution_policies.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/elements/oneDPL/source/parallel_api/execution_policies.rst b/source/elements/oneDPL/source/parallel_api/execution_policies.rst index 299f046e6..c11b5fcd5 100644 --- a/source/elements/oneDPL/source/parallel_api/execution_policies.rst +++ b/source/elements/oneDPL/source/parallel_api/execution_policies.rst @@ -225,8 +225,8 @@ from its template argument and should be used with ``std::decay`` or similar 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 strongly recommended. - Those in ``namespace oneapi::dpl::execution`` are provided for backward compatibility and might get deprecated. + For 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. .. _`C++ Standard`: https://isocpp.org/std/the-standard .. _`SYCL`: https://registry.khronos.org/SYCL/specs/sycl-2020/html/sycl-2020.html From 7138a9428c201e74c761aedebfebadc40a3748b2 Mon Sep 17 00:00:00 2001 From: Alexey Kukanov Date: Tue, 20 Aug 2024 16:55:28 +0200 Subject: [PATCH 4/9] Fix HTML build error --- .../elements/oneDPL/source/parallel_api/execution_policies.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/elements/oneDPL/source/parallel_api/execution_policies.rst b/source/elements/oneDPL/source/parallel_api/execution_policies.rst index c11b5fcd5..e8a1883f2 100644 --- a/source/elements/oneDPL/source/parallel_api/execution_policies.rst +++ b/source/elements/oneDPL/source/parallel_api/execution_policies.rst @@ -37,7 +37,7 @@ 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 `_. + Implementations and programs should instead use the :ref:`oneDPL type trait `. Device Execution Policy +++++++++++++++++++++++ From dab98a2a6ebf3ffb41d9befde19c74bddbd2968e Mon Sep 17 00:00:00 2001 From: Alexey Kukanov Date: Tue, 20 Aug 2024 16:58:07 +0200 Subject: [PATCH 5/9] Change the order of declarations --- .../source/parallel_api/execution_policies.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/source/elements/oneDPL/source/parallel_api/execution_policies.rst b/source/elements/oneDPL/source/parallel_api/execution_policies.rst index e8a1883f2..d8b7a1619 100644 --- a/source/elements/oneDPL/source/parallel_api/execution_policies.rst +++ b/source/elements/oneDPL/source/parallel_api/execution_policies.rst @@ -193,6 +193,12 @@ function overload resolution: namespace oneapi { namespace dpl { + template + struct is_execution_policy { /*see below*/ }; + + template + inline constexpr bool is_execution_policy_v = oneapi::dpl::is_execution_policy::value; + namespace execution { template @@ -203,12 +209,6 @@ function overload resolution: } - template - struct is_execution_policy { /*see below*/ }; - - template - inline constexpr bool is_execution_policy_v = oneapi::dpl::is_execution_policy::value; - } } From 7f4f416e4ac70ec64486c220cb67d0263ec88ae7 Mon Sep 17 00:00:00 2001 From: Alexey Kukanov Date: Tue, 20 Aug 2024 20:56:49 +0200 Subject: [PATCH 6/9] Address review feedback --- .../oneDPL/source/parallel_api/execution_policies.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/elements/oneDPL/source/parallel_api/execution_policies.rst b/source/elements/oneDPL/source/parallel_api/execution_policies.rst index d8b7a1619..6f1ae5eb0 100644 --- a/source/elements/oneDPL/source/parallel_api/execution_policies.rst +++ b/source/elements/oneDPL/source/parallel_api/execution_policies.rst @@ -183,7 +183,7 @@ argument. If no policy object is provided, the new policy is constructed from `` Execution Policy Type Trait +++++++++++++++++++++++++++ -oneDPL provides type trait utilities to detect at compile time its execution policy types for the purpose of +oneDPL provides type trait utilities to detect its execution policy types at compile time for the purpose of function overload resolution: .. code:: cpp @@ -219,13 +219,13 @@ are defined. ``is_execution_policy`` must have the characteristics of ``std::true_type`` if ``T`` is one of the above specified or implementation-defined 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 and should be used with ``std::decay`` or similar type transformation utilities. +from its template argument. *[Hint: Use it with* ``std::decay`` *or similar type transformation utilities.]* .. 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 strongly recommended. Those + 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. .. _`C++ Standard`: https://isocpp.org/std/the-standard From b8a777b0facd593e6a02cdcc337b5d6122eb23f6 Mon Sep 17 00:00:00 2001 From: Alexey Kukanov Date: Thu, 22 Aug 2024 11:21:13 +0200 Subject: [PATCH 7/9] Apply suggestions Co-authored-by: Ruslan Arutyunyan --- .../elements/oneDPL/source/parallel_api/execution_policies.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/elements/oneDPL/source/parallel_api/execution_policies.rst b/source/elements/oneDPL/source/parallel_api/execution_policies.rst index 6f1ae5eb0..6fc54426d 100644 --- a/source/elements/oneDPL/source/parallel_api/execution_policies.rst +++ b/source/elements/oneDPL/source/parallel_api/execution_policies.rst @@ -219,7 +219,7 @@ are defined. ``is_execution_policy`` must have the characteristics of ``std::true_type`` if ``T`` is one of the above specified or implementation-defined 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. *[Hint: Use it with* ``std::decay`` *or similar type transformation utilities.]* +from its template argument. *[Hint: Use it with* ``std::decay_t`` *or similar type transformation utilities.]* .. note:: The ``oneapi::dpl::execution::is_execution_policy`` class originated in the oneDPL specification version 1.0, From f3b68a0f330f930e00687dbc84e7d1b7bf041de6 Mon Sep 17 00:00:00 2001 From: Alexey Kukanov Date: Thu, 22 Aug 2024 17:04:27 +0200 Subject: [PATCH 8/9] Use C++ and SYCL formatting for in-text notes --- .../elements/oneDPL/source/parallel_api/execution_policies.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/elements/oneDPL/source/parallel_api/execution_policies.rst b/source/elements/oneDPL/source/parallel_api/execution_policies.rst index 6fc54426d..8631f1b29 100644 --- a/source/elements/oneDPL/source/parallel_api/execution_policies.rst +++ b/source/elements/oneDPL/source/parallel_api/execution_policies.rst @@ -219,7 +219,7 @@ are defined. ``is_execution_policy`` must have the characteristics of ``std::true_type`` if ``T`` is one of the above specified or implementation-defined 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. *[Hint: Use it with* ``std::decay_t`` *or similar type transformation utilities.]* +from its template argument. [*Note*: Use it with ``std::decay_t`` or similar type transformation utilities. -- *end note*] .. note:: The ``oneapi::dpl::execution::is_execution_policy`` class originated in the oneDPL specification version 1.0, From b6724054e58d8f3272e4e1d7a059dd7d8b0f3e04 Mon Sep 17 00:00:00 2001 From: Alexey Kukanov Date: Sat, 21 Sep 2024 22:15:45 +0200 Subject: [PATCH 9/9] Cosmetic improvements --- .../source/parallel_api/execution_policies.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/source/elements/oneDPL/source/parallel_api/execution_policies.rst b/source/elements/oneDPL/source/parallel_api/execution_policies.rst index 8631f1b29..d380d81ed 100644 --- a/source/elements/oneDPL/source/parallel_api/execution_policies.rst +++ b/source/elements/oneDPL/source/parallel_api/execution_policies.rst @@ -69,6 +69,7 @@ the `SYCL`_ device and queue to run oneDPL algorithms. template device_policy make_device_policy( const device_policy& = dpcpp_default ); + } } } @@ -197,7 +198,7 @@ function overload resolution: struct is_execution_policy { /*see below*/ }; template - inline constexpr bool is_execution_policy_v = oneapi::dpl::is_execution_policy::value; + constexpr bool is_execution_policy_v = oneapi::dpl::is_execution_policy::value; namespace execution { @@ -205,10 +206,9 @@ function overload resolution: struct is_execution_policy { /*see below*/ }; template - inline constexpr bool is_execution_policy_v = oneapi::dpl::execution::is_execution_policy::value; + constexpr bool is_execution_policy_v = oneapi::dpl::execution::is_execution_policy::value; } - } } @@ -216,11 +216,6 @@ function overload resolution: to the same class template. It is unspecified in which namespace the underlying class template and its specializations are defined. -``is_execution_policy`` must have the characteristics of ``std::true_type`` if ``T`` is one of the above specified -or implementation-defined 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*] - .. 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. @@ -228,5 +223,10 @@ from its template argument. [*Note*: Use it with ``std::decay_t`` or similar 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