From ff342a7e945d1eb69c2e1eebbc281b4ce60eafb4 Mon Sep 17 00:00:00 2001 From: Alexey Kukanov Date: Tue, 20 Aug 2024 15:10:08 +0200 Subject: [PATCH 01/12] 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 e405602e28..b7ca9fc102 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 02/12] 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 b7ca9fc102..299f046e6b 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 03/12] 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 299f046e6b..c11b5fcd52 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 04/12] 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 c11b5fcd52..e8a1883f25 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 05/12] 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 e8a1883f25..d8b7a1619b 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 06/12] 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 d8b7a1619b..6f1ae5eb0b 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 07/12] 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 6f1ae5eb0b..6fc54426d3 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 08/12] 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 6fc54426d3..8631f1b299 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 0c955d7699d569c27902854c354945759eb98afe Mon Sep 17 00:00:00 2001 From: Alexey Kukanov Date: Sat, 21 Sep 2024 22:15:45 +0200 Subject: [PATCH 09/12] Cosmetic improvements --- .../source/parallel_api/execution_policies.rst | 15 +++++++-------- 1 file changed, 7 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 8631f1b299..241770d5a6 100644 --- a/source/elements/oneDPL/source/parallel_api/execution_policies.rst +++ b/source/elements/oneDPL/source/parallel_api/execution_policies.rst @@ -197,7 +197,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 +205,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 +215,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 +222,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 From c4a053f1fdbb008647a421d9a84fae58ac890e3a Mon Sep 17 00:00:00 2001 From: Alexey Kukanov Date: Wed, 9 Oct 2024 16:01:34 +0200 Subject: [PATCH 10/12] 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 241770d5a6..b39a25a5f3 100644 --- a/source/elements/oneDPL/source/parallel_api/execution_policies.rst +++ b/source/elements/oneDPL/source/parallel_api/execution_policies.rst @@ -197,7 +197,7 @@ function overload resolution: struct is_execution_policy { /*see below*/ }; template - constexpr bool is_execution_policy_v = oneapi::dpl::is_execution_policy::value; + constexpr inline bool is_execution_policy_v = oneapi::dpl::is_execution_policy::value; namespace execution { @@ -205,7 +205,7 @@ function overload resolution: struct is_execution_policy { /*see below*/ }; template - constexpr bool is_execution_policy_v = oneapi::dpl::execution::is_execution_policy::value; + constexpr inline bool is_execution_policy_v = oneapi::dpl::execution::is_execution_policy::value; } } @@ -219,7 +219,7 @@ are defined. 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 + 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`` must have the characteristics of ``std::true_type`` if ``T`` is one of the above specified or From eb5b8440405c56611139e246251f26d9999399b3 Mon Sep 17 00:00:00 2001 From: Alexey Kukanov Date: Thu, 10 Oct 2024 12:25:19 +0200 Subject: [PATCH 11/12] Swap constexpr and inline --- .../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 b39a25a5f3..4e7a8ab35c 100644 --- a/source/elements/oneDPL/source/parallel_api/execution_policies.rst +++ b/source/elements/oneDPL/source/parallel_api/execution_policies.rst @@ -197,7 +197,7 @@ function overload resolution: struct is_execution_policy { /*see below*/ }; template - constexpr inline bool is_execution_policy_v = oneapi::dpl::is_execution_policy::value; + inline constexpr bool is_execution_policy_v = oneapi::dpl::is_execution_policy::value; namespace execution { @@ -205,7 +205,7 @@ function overload resolution: struct is_execution_policy { /*see below*/ }; template - constexpr inline bool is_execution_policy_v = oneapi::dpl::execution::is_execution_policy::value; + inline constexpr bool is_execution_policy_v = oneapi::dpl::execution::is_execution_policy::value; } } From ff844ac11fbd0f14566c825585e9cef41d9f3fe1 Mon Sep 17 00:00:00 2001 From: Alexey Kukanov Date: Thu, 10 Oct 2024 15:14:56 +0200 Subject: [PATCH 12/12] Rephrase a sentence --- .../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 4e7a8ab35c..0054b22f2d 100644 --- a/source/elements/oneDPL/source/parallel_api/execution_policies.rst +++ b/source/elements/oneDPL/source/parallel_api/execution_policies.rst @@ -211,9 +211,9 @@ function overload resolution: } } -``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. +``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,