From 6e0d20ad5408cbf296fb9ef2953ead47b23ca9d8 Mon Sep 17 00:00:00 2001 From: Alexey Kukanov Date: Mon, 6 Oct 2025 15:55:21 +0200 Subject: [PATCH 1/4] Add synopsis and a short description for new policy instance templates --- .../parallel_api/execution_policies.rst | 21 +++++++++++++++++-- 1 file changed, 19 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 1fab6ec9c..ce2d069ea 100644 --- a/source/elements/oneDPL/source/parallel_api/execution_policies.rst +++ b/source/elements/oneDPL/source/parallel_api/execution_policies.rst @@ -56,6 +56,15 @@ A device execution policy represents a `SYCL`_ device and queue to run oneDPL al class device_policy; inline const device_policy<> dpcpp_default; + + template + const device_policy dpdefault; + + template + const device_policy dpgpu; + + template + const device_policy dpcpu; template device_policy @@ -151,13 +160,21 @@ Return the queue the policy is associated with. Allow implicit conversion of the policy to a ``sycl::queue`` object. -Predefined Device Policy -^^^^^^^^^^^^^^^^^^^^^^^^ +Predefined Device Policies +^^^^^^^^^^^^^^^^^^^^^^^^^^ ``dpcpp_default`` is a predefined execution policy object to run algorithms on the default SYCL device. It is a global immutable (``const``) instance of type ``device_policy<>``. [*Note*: ``dpcpp_default`` can be copied but cannot be moved. -- *end note*] +``dpdefault``, ``dpgpu``, and `dpcpu`` are variable templates for creating ``device_policy`` objects, +possibly with user-provided kernel names, to run algorithms on the default SYCL device, a GPU device, +and a CPU device, respectively. A policy object instantiated from one of these templates is associated +with a SYCL queue constructed with the device selector appropriate for the template used. +[*Example*: ``dpgpu<>`` is associated with a queue created by ``sycl::gpu_selector_v``. -- *end example*] + + + make_device_policy Function ^^^^^^^^^^^^^^^^^^^^^^^^^^^ From 46a06692dc41e3ab9af335dee7d134ed71af3809 Mon Sep 17 00:00:00 2001 From: Alexey Kukanov Date: Mon, 6 Oct 2025 20:46:00 +0200 Subject: [PATCH 2/4] Improve the wording. Add a note about exceptions. --- .../oneDPL/source/parallel_api/execution_policies.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/source/elements/oneDPL/source/parallel_api/execution_policies.rst b/source/elements/oneDPL/source/parallel_api/execution_policies.rst index ce2d069ea..7f70940f5 100644 --- a/source/elements/oneDPL/source/parallel_api/execution_policies.rst +++ b/source/elements/oneDPL/source/parallel_api/execution_policies.rst @@ -168,12 +168,13 @@ It is a global immutable (``const``) instance of type ``device_policy<>``. [*Note*: ``dpcpp_default`` can be copied but cannot be moved. -- *end note*] ``dpdefault``, ``dpgpu``, and `dpcpu`` are variable templates for creating ``device_policy`` objects, -possibly with user-provided kernel names, to run algorithms on the default SYCL device, a GPU device, -and a CPU device, respectively. A policy object instantiated from one of these templates is associated -with a SYCL queue constructed with the device selector appropriate for the template used. +possibly with explicit kernel names, to run algorithms on the default SYCL device, a GPU device, +and a CPU device, respectively. An object instantiated from one of these templates is a global +immutable ``device_policy`` object. It is associated with a SYCL queue constructed with +the SYCL device selector that corresponds to the used variable template. [*Example*: ``dpgpu<>`` is associated with a queue created by ``sycl::gpu_selector_v``. -- *end example*] - +Creation or use of a `dpgpu` or a `dpcpu` policy object can throw ``sycl::exception`` if no appropriate device is found. make_device_policy Function ^^^^^^^^^^^^^^^^^^^^^^^^^^^ From 4342a38a16c756b89eba8eed8e131922e8f6f26b Mon Sep 17 00:00:00 2001 From: Alexey Kukanov Date: Mon, 6 Oct 2025 20:51:35 +0200 Subject: [PATCH 3/4] Fix the RST syntax for inlined code --- .../oneDPL/source/parallel_api/execution_policies.rst | 5 +++-- 1 file changed, 3 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 7f70940f5..d65a833d6 100644 --- a/source/elements/oneDPL/source/parallel_api/execution_policies.rst +++ b/source/elements/oneDPL/source/parallel_api/execution_policies.rst @@ -167,14 +167,15 @@ Predefined Device Policies It is a global immutable (``const``) instance of type ``device_policy<>``. [*Note*: ``dpcpp_default`` can be copied but cannot be moved. -- *end note*] -``dpdefault``, ``dpgpu``, and `dpcpu`` are variable templates for creating ``device_policy`` objects, +``dpdefault``, ``dpgpu``, and ``dpcpu`` are variable templates for creating ``device_policy`` objects, possibly with explicit kernel names, to run algorithms on the default SYCL device, a GPU device, and a CPU device, respectively. An object instantiated from one of these templates is a global immutable ``device_policy`` object. It is associated with a SYCL queue constructed with the SYCL device selector that corresponds to the used variable template. [*Example*: ``dpgpu<>`` is associated with a queue created by ``sycl::gpu_selector_v``. -- *end example*] -Creation or use of a `dpgpu` or a `dpcpu` policy object can throw ``sycl::exception`` if no appropriate device is found. +Creation or use of a ``dpgpu`` or a ``dpcpu`` policy object can throw ``sycl::exception`` +if no appropriate device is found. make_device_policy Function ^^^^^^^^^^^^^^^^^^^^^^^^^^^ From a32d7939118d01b6b240779696e72064b5a8ea9c Mon Sep 17 00:00:00 2001 From: Alexey Kukanov Date: Tue, 7 Oct 2025 14:29:11 +0200 Subject: [PATCH 4/4] Require non-throwing construction of predefined policies --- .../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 d65a833d6..afa496d14 100644 --- a/source/elements/oneDPL/source/parallel_api/execution_policies.rst +++ b/source/elements/oneDPL/source/parallel_api/execution_policies.rst @@ -174,8 +174,8 @@ immutable ``device_policy`` object. It is associated with a SYCL queue construct the SYCL device selector that corresponds to the used variable template. [*Example*: ``dpgpu<>`` is associated with a queue created by ``sycl::gpu_selector_v``. -- *end example*] -Creation or use of a ``dpgpu`` or a ``dpcpu`` policy object can throw ``sycl::exception`` -if no appropriate device is found. +Construction of predefined device policies must not throw exceptions. +Use of a ``dpgpu`` or a ``dpcpu`` policy object can throw ``sycl::exception`` if no appropriate device is found. make_device_policy Function ^^^^^^^^^^^^^^^^^^^^^^^^^^^