Skip to content

Commit a56d34b

Browse files
akukanovakukanov
authored
[oneDPL] Create a dedicated page for execution policies (#563)
1 parent e5f92fe commit a56d34b

2 files changed

Lines changed: 189 additions & 175 deletions

File tree

‎source/elements/oneDPL/source/parallel_api.rst‎

Lines changed: 5 additions & 175 deletions
Original file line numberDiff line numberDiff line change
@@ -7,185 +7,15 @@ Parallel API
77

88
oneDPL provides the set of parallel algorithms as defined by the `C++ Standard`_,
99
including parallel algorithms added in the 6th edition known as C++20.
10-
All those algorithms work with *C++ Standard aligned execution policies* and with *DPC++
11-
execution policies*.
10+
All those algorithms work with *C++ Standard aligned execution policies* and with
11+
*device execution policies*.
1212

1313
Additionally, oneDPL provides wrapper functions for `SYCL`_ buffers, special iterators, and
1414
a set of non-standard parallel algorithms.
1515

16-
C++ Standard aligned execution policies
17-
+++++++++++++++++++++++++++++++++++++++
16+
.. toctree::
1817

19-
oneDPL has the set of execution policies and related utilities that are semantically aligned
20-
with the `C++ Standard`_, 6th edition (C++20):
21-
22-
.. code:: cpp
23-
24-
// Defined in <oneapi/dpl/execution>
25-
26-
namespace oneapi {
27-
namespace dpl {
28-
namespace execution {
29-
30-
class sequenced_policy { /*unspecified*/ };
31-
class parallel_policy { /*unspecified*/ };
32-
class parallel_unsequenced_policy { /*unspecified*/ };
33-
class unsequenced_policy { /*unspecified*/ };
34-
35-
inline constexpr sequenced_policy seq { /*unspecified*/ };
36-
inline constexpr parallel_policy par { /*unspecified*/ };
37-
inline constexpr parallel_unsequenced_policy par_unseq { /*unspecified*/ };
38-
inline constexpr unsequenced_policy unseq { /*unspecified*/ };
39-
40-
template <class T>
41-
struct is_execution_policy;
42-
43-
template <class T>
44-
inline constexpr bool is_execution_policy_v = oneapi::dpl::execution::is_execution_policy<T>::value;
45-
}
46-
}
47-
}
48-
49-
See "Execution policies" in the `C++ Standard`_ for more information.
50-
51-
DPC++ Execution Policy
52-
++++++++++++++++++++++
53-
54-
A DPC++ execution policy class :code:`oneapi::dpl::execution::device_policy` specifies
55-
where and how an algorithm runs.
56-
57-
.. code:: cpp
58-
59-
// Defined in <oneapi/dpl/execution>
60-
61-
namespace oneapi {
62-
namespace dpl {
63-
namespace execution {
64-
65-
template <typename KernelName = /*unspecified*/>
66-
class device_policy;
67-
68-
const device_policy<> dpcpp_default;
69-
70-
template <typename KernelName = /*unspecified*/>
71-
device_policy<KernelName>
72-
make_device_policy( sycl::queue );
73-
74-
template <typename KernelName = /*unspecified*/>
75-
device_policy<KernelName>
76-
make_device_policy( sycl::device );
77-
78-
template <typename NewKernelName, typename OldKernelName>
79-
device_policy<NewKernelName>
80-
make_device_policy( const device_policy<OldKernelName>& = dpcpp_default );
81-
}
82-
}
83-
}
84-
85-
``dpcpp_default`` is a predefined execution policy object to run algorithms on the default DPC++ device.
86-
87-
device_policy class
88-
^^^^^^^^^^^^^^^^^^^
89-
90-
.. code:: cpp
91-
92-
template <typename KernelName = /*unspecified*/>
93-
class device_policy
94-
{
95-
public:
96-
using kernel_name = KernelName;
97-
98-
device_policy();
99-
template <typename OtherName>
100-
device_policy( const device_policy<OtherName>& );
101-
explicit device_policy( sycl::queue );
102-
explicit device_policy( sycl::device );
103-
104-
sycl::queue queue() const;
105-
operator sycl::queue() const;
106-
};
107-
108-
An object of the ``device_policy`` type is associated with a ``sycl::queue`` that is used
109-
to run algorithms on a DPC++ compliant device. When an algorithm runs with ``device_policy``
110-
it is capable of processing SYCL buffers (passed via :code:`oneapi::dpl::begin/end`),
111-
data in the host memory and data in Unified Shared Memory (USM), including USM device memory.
112-
Data placed in the host memory and USM can only be passed to oneDPL algorithms
113-
as pointers and random access iterators. The way to transfer data from the host memory
114-
to a device and back is unspecified; per-element data movement to/from a temporary storage
115-
is a possible valid implementation.
116-
117-
The ``KernelName`` template parameter, also aliased as ``kernel_name`` within the class template,
118-
is to explicitly provide a name for DPC++ kernels executed by an algorithm the policy is passed to.
119-
120-
.. code:: cpp
121-
122-
device_policy()
123-
124-
Construct a policy object associated with a queue created with the default device selector.
125-
126-
.. code:: cpp
127-
128-
template <typename OtherName>
129-
device_policy( const device_policy<OtherName>& policy )
130-
131-
Construct a policy object associated with the same queue as ``policy``, by changing
132-
the kernel name of the given policy to ``kernel_name`` defined for the new policy.
133-
134-
.. code:: cpp
135-
136-
explicit device_policy( sycl::queue queue )
137-
138-
Construct a policy object associated with the given queue.
139-
140-
.. code:: cpp
141-
142-
explicit device_policy( sycl::device device )
143-
144-
Construct a policy object associated with a queue created for the given device.
145-
146-
.. code:: cpp
147-
148-
sycl::queue queue() const
149-
150-
Return the queue the policy is associated with.
151-
152-
.. code:: cpp
153-
154-
operator sycl::queue() const
155-
156-
Allow implicit conversion of the policy to a ``sycl::queue`` object.
157-
158-
make_device_policy function
159-
^^^^^^^^^^^^^^^^^^^^^^^^^^^
160-
161-
The ``make_device_policy`` function templates simplify ``device_policy`` creation.
162-
163-
.. code:: cpp
164-
165-
template <typename KernelName = /*unspecified*/>
166-
device_policy<KernelName>
167-
make_device_policy( sycl::queue queue )
168-
169-
Return a policy object associated with ``queue``, with a kernel name possibly provided
170-
as the template argument, otherwise unspecified.
171-
172-
.. code:: cpp
173-
174-
template <typename KernelName = /*unspecified*/>
175-
device_policy<KernelName>
176-
make_device_policy( sycl::device device )
177-
178-
Return a policy object to run algorithms on ``device``, with a kernel name possibly provided
179-
as the template argument, otherwise unspecified.
180-
181-
.. code:: cpp
182-
183-
template <typename NewKernelName, typename OldKernelName>
184-
device_policy<NewKernelName>
185-
make_device_policy( const device_policy<OldKernelName>& policy = dpcpp_default )
186-
187-
Return a policy object constructed from ``policy``, with a new kernel name provided as the template
188-
argument. If no policy object is provided, the new policy is constructed from ``dpcpp_default``.
18+
parallel_api/execution_policies.rst
18919

19020
Buffer wrappers
19121
+++++++++++++++
@@ -226,7 +56,7 @@ Buffer wrappers
22656
}
22757
22858
``oneapi::dpl::begin`` and ``oneapi::dpl::end`` are helper functions
229-
for passing DPC++ buffers to oneDPL algorithms.
59+
for passing SYCL buffers to oneDPL algorithms.
23060
These functions accept a buffer and return an object
23161
of an unspecified type that satisfies the following requirements:
23262

‎source/elements/oneDPL/source/parallel_api/execution_policies.rst‎

Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
.. SPDX-FileCopyrightText: 2019-2022 Intel Corporation
2+
.. SPDX-FileCopyrightText: Contributors to the oneAPI Specification project.
3+
..
4+
.. SPDX-License-Identifier: CC-BY-4.0
5+
6+
Execution policies
7+
------------------
8+
9+
C++ Standard aligned execution policies
10+
+++++++++++++++++++++++++++++++++++++++
11+
12+
oneDPL has the set of execution policies and related utilities that are semantically aligned
13+
with the `C++ Standard`_, 6th edition (C++20):
14+
15+
.. code:: cpp
16+
17+
// Defined in <oneapi/dpl/execution>
18+
19+
namespace oneapi {
20+
namespace dpl {
21+
namespace execution {
22+
23+
class sequenced_policy { /*unspecified*/ };
24+
class parallel_policy { /*unspecified*/ };
25+
class parallel_unsequenced_policy { /*unspecified*/ };
26+
class unsequenced_policy { /*unspecified*/ };
27+
28+
inline constexpr sequenced_policy seq { /*unspecified*/ };
29+
inline constexpr parallel_policy par { /*unspecified*/ };
30+
inline constexpr parallel_unsequenced_policy par_unseq { /*unspecified*/ };
31+
inline constexpr unsequenced_policy unseq { /*unspecified*/ };
32+
33+
template <class T>
34+
struct is_execution_policy;
35+
36+
template <class T>
37+
inline constexpr bool is_execution_policy_v = oneapi::dpl::execution::is_execution_policy<T>::value;
38+
}
39+
}
40+
}
41+
42+
See "Execution policies" in the `C++ Standard`_ for more information.
43+
44+
Device Execution Policy
45+
+++++++++++++++++++++++
46+
47+
A device execution policy class :code:`oneapi::dpl::execution::device_policy` specifies
48+
the `SYCL`_ device and queue to run oneDPL algorithms.
49+
50+
.. code:: cpp
51+
52+
// Defined in <oneapi/dpl/execution>
53+
54+
namespace oneapi {
55+
namespace dpl {
56+
namespace execution {
57+
58+
template <typename KernelName = /*unspecified*/>
59+
class device_policy;
60+
61+
const device_policy<> dpcpp_default;
62+
63+
template <typename KernelName = /*unspecified*/>
64+
device_policy<KernelName>
65+
make_device_policy( sycl::queue );
66+
67+
template <typename KernelName = /*unspecified*/>
68+
device_policy<KernelName>
69+
make_device_policy( sycl::device );
70+
71+
template <typename NewKernelName, typename OldKernelName>
72+
device_policy<NewKernelName>
73+
make_device_policy( const device_policy<OldKernelName>& = dpcpp_default );
74+
}
75+
}
76+
}
77+
78+
``dpcpp_default`` is a predefined execution policy object to run algorithms on the default `SYCL`_ device.
79+
80+
device_policy class
81+
^^^^^^^^^^^^^^^^^^^
82+
83+
.. code:: cpp
84+
85+
template <typename KernelName = /*unspecified*/>
86+
class device_policy
87+
{
88+
public:
89+
using kernel_name = KernelName;
90+
91+
device_policy();
92+
template <typename OtherName>
93+
device_policy( const device_policy<OtherName>& );
94+
explicit device_policy( sycl::queue );
95+
explicit device_policy( sycl::device );
96+
97+
sycl::queue queue() const;
98+
operator sycl::queue() const;
99+
};
100+
101+
An object of the ``device_policy`` type is associated with a ``sycl::queue`` that is used
102+
to run algorithms on a SYCL device. When an algorithm runs with ``device_policy``
103+
it is capable of processing SYCL buffers (passed via :code:`oneapi::dpl::begin/end`),
104+
data in the host memory and data in Unified Shared Memory (USM), including USM device memory.
105+
Data placed in the host memory and USM can only be passed to oneDPL algorithms
106+
as pointers and random access iterators. The way to transfer data from the host memory
107+
to a device and back is unspecified; per-element data movement to/from a temporary storage
108+
is a possible valid implementation.
109+
110+
The ``KernelName`` template parameter, also aliased as ``kernel_name`` within the class template,
111+
is to explicitly provide a name for SYCL kernels executed by an algorithm the policy is passed to.
112+
113+
.. code:: cpp
114+
115+
device_policy()
116+
117+
Construct a policy object associated with a queue created with the default device selector.
118+
119+
.. code:: cpp
120+
121+
template <typename OtherName>
122+
device_policy( const device_policy<OtherName>& policy )
123+
124+
Construct a policy object associated with the same queue as ``policy``, by changing
125+
the kernel name of the given policy to ``kernel_name`` defined for the new policy.
126+
127+
.. code:: cpp
128+
129+
explicit device_policy( sycl::queue queue )
130+
131+
Construct a policy object associated with the given queue.
132+
133+
.. code:: cpp
134+
135+
explicit device_policy( sycl::device device )
136+
137+
Construct a policy object associated with a queue created for the given device.
138+
139+
.. code:: cpp
140+
141+
sycl::queue queue() const
142+
143+
Return the queue the policy is associated with.
144+
145+
.. code:: cpp
146+
147+
operator sycl::queue() const
148+
149+
Allow implicit conversion of the policy to a ``sycl::queue`` object.
150+
151+
make_device_policy function
152+
^^^^^^^^^^^^^^^^^^^^^^^^^^^
153+
154+
The ``make_device_policy`` function templates simplify ``device_policy`` creation.
155+
156+
.. code:: cpp
157+
158+
template <typename KernelName = /*unspecified*/>
159+
device_policy<KernelName>
160+
make_device_policy( sycl::queue queue )
161+
162+
Return a policy object associated with ``queue``, with a kernel name possibly provided
163+
as the template argument, otherwise unspecified.
164+
165+
.. code:: cpp
166+
167+
template <typename KernelName = /*unspecified*/>
168+
device_policy<KernelName>
169+
make_device_policy( sycl::device device )
170+
171+
Return a policy object to run algorithms on ``device``, with a kernel name possibly provided
172+
as the template argument, otherwise unspecified.
173+
174+
.. code:: cpp
175+
176+
template <typename NewKernelName, typename OldKernelName>
177+
device_policy<NewKernelName>
178+
make_device_policy( const device_policy<OldKernelName>& policy = dpcpp_default )
179+
180+
Return a policy object constructed from ``policy``, with a new kernel name provided as the template
181+
argument. If no policy object is provided, the new policy is constructed from ``dpcpp_default``.
182+
183+
.. _`C++ Standard`: https://isocpp.org/std/the-standard
184+
.. _`SYCL`: https://registry.khronos.org/SYCL/specs/sycl-2020/html/sycl-2020.html

0 commit comments

Comments
 (0)