Skip to content

Commit

Permalink
[oneDPL] Specify copy and move semantics for device_policy (#594)
Browse files Browse the repository at this point in the history
  • Loading branch information
akukanov authored Oct 14, 2024
1 parent 4ac2613 commit 590a1f0
Showing 1 changed file with 23 additions and 11 deletions.
34 changes: 23 additions & 11 deletions source/elements/oneDPL/source/parallel_api/execution_policies.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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 <exec-policy-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
Expand All @@ -56,7 +55,7 @@ the `SYCL`_ device and queue to run oneDPL algorithms.
template <typename KernelName = /*unspecified*/>
class device_policy;
const device_policy<> dpcpp_default;
inline const device_policy<> dpcpp_default;
template <typename KernelName = /*unspecified*/>
device_policy<KernelName>
Expand All @@ -69,12 +68,11 @@ the `SYCL`_ device and queue to run oneDPL algorithms.
template <typename NewKernelName, typename OldKernelName>
device_policy<NewKernelName>
make_device_policy( const device_policy<OldKernelName>& = dpcpp_default );
}
}
}
``dpcpp_default`` is a predefined execution policy object to run algorithms on the default `SYCL`_ device.

device_policy Class
^^^^^^^^^^^^^^^^^^^

Expand All @@ -99,15 +97,22 @@ 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.

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()
Expand All @@ -119,8 +124,8 @@ Construct a policy object associated with a queue created with the default devic
template <typename OtherName>
device_policy( const device_policy<OtherName>& 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
Expand All @@ -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
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Expand Down

0 comments on commit 590a1f0

Please sign in to comment.