From 590a1f01dfd463b0d8c431f507473dd4d7501118 Mon Sep 17 00:00:00 2001 From: Alexey Kukanov Date: Mon, 14 Oct 2024 19:30:52 +0200 Subject: [PATCH] [oneDPL] Specify copy and move semantics for device_policy (#594) --- .../parallel_api/execution_policies.rst | 34 +++++++++++++------ 1 file changed, 23 insertions(+), 11 deletions(-) diff --git a/source/elements/oneDPL/source/parallel_api/execution_policies.rst b/source/elements/oneDPL/source/parallel_api/execution_policies.rst index 0054b22f2..cc7e84e73 100644 --- a/source/elements/oneDPL/source/parallel_api/execution_policies.rst +++ b/source/elements/oneDPL/source/parallel_api/execution_policies.rst @@ -39,11 +39,10 @@ See "Execution policies" in the `C++ Standard`_ for more information. 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 -+++++++++++++++++++++++ +Device Execution Policies ++++++++++++++++++++++++++ -A device execution policy class ``oneapi::dpl::execution::device_policy`` specifies -the `SYCL`_ device and queue to run oneDPL algorithms. +A device execution policy represents a `SYCL`_ device and queue to run oneDPL algorithms. .. code:: cpp @@ -56,7 +55,7 @@ the `SYCL`_ device and queue to run oneDPL algorithms. template class device_policy; - const device_policy<> dpcpp_default; + inline const device_policy<> dpcpp_default; template device_policy @@ -69,12 +68,11 @@ the `SYCL`_ device and queue to run oneDPL algorithms. template device_policy make_device_policy( const device_policy& = dpcpp_default ); + } } } -``dpcpp_default`` is a predefined execution policy object to run algorithms on the default `SYCL`_ device. - device_policy Class ^^^^^^^^^^^^^^^^^^^ @@ -99,8 +97,8 @@ device_policy Class An object of the ``device_policy`` type is associated with a ``sycl::queue`` that is used to run algorithms on a SYCL device. When an algorithm runs with ``device_policy`` it is capable of processing SYCL buffers (passed via ``oneapi::dpl::begin/end``), -data in the host memory and data in Unified Shared Memory (USM), including USM device memory. -Data placed in the host memory and USM can only be passed to oneDPL algorithms +data in the host memory and data in Unified Shared Memory (USM), including device USM. +Data placed in the host memory and USM can be passed to oneDPL algorithms as pointers and random access iterators. The way to transfer data from the host memory to a device and back is unspecified; per-element data movement to/from a temporary storage is a possible valid implementation. @@ -108,6 +106,13 @@ is a possible valid implementation. The ``KernelName`` template parameter, also aliased as ``kernel_name`` within the class template, is to explicitly provide a name for SYCL kernels executed by an algorithm the policy is passed to. +The ``device_policy`` type is copy-constructible, copy-assignable, move-constructible and move-assignable. +A policy instance constructed as or assigned a copy of another instance is associated with +a ``sycl::queue`` that compares equal, as defined by `SYCL`_, to the queue of that other instance. +A policy instance constructed as or assigned a move of another instance is associated with the queue +of that other instance without copying it. It is unspecified whether the moved-from policy instance +is associated with any queue after the move. + .. code:: cpp device_policy() @@ -119,8 +124,8 @@ Construct a policy object associated with a queue created with the default devic template device_policy( const device_policy& policy ) -Construct a policy object associated with the same queue as ``policy``, by changing -the kernel name of the given policy to ``kernel_name`` defined for the new policy. +Construct a policy object as if by copying ``policy`` and changing +the kernel name to ``kernel_name`` defined for the new policy. .. code:: cpp @@ -146,6 +151,13 @@ Return the queue the policy is associated with. Allow implicit conversion of the policy to a ``sycl::queue`` object. +Predefined Device Policy +^^^^^^^^^^^^^^^^^^^^^^^^ + +``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*] + make_device_policy Function ^^^^^^^^^^^^^^^^^^^^^^^^^^^