DPCT Namespace Usage Guide¶
The DPCT namespace provides helper functions and macros to assist the migration of input source code. DPCT namespace helper functions are implemented in header files and are available in the include folder (include/dpct) of the Intel® DPC++ Compatibility Tool install path. These header files are intended to become part of your new DPC++ code generated by the Intel® DPC++ Compatibility Tool. You can copy these header files if needed and include them with the generated code.
There are two namespaces defined: dpct::
and dpct::detail::
. dpct::
is used in the code generated by the Intel® DPC++ Compatibility Tool. dpct::detail::
is
an internal implementation and should not be used in DPC++ source files directly,
as the API and implementations inside the dpct::detail::
namespace can be
changed at any time without notice.
Note
After migration, it is recommended that you continue development using DPC++, SYCL, and C++ standard APIs, rather than continue development based on DPCT namespace helper functions and macros.
The following sections describe different domains of helper functions and macros in more detail.
Macros¶
There are three macros used to control the behavior of the helper
functions: DPCT_USM_LEVEL_NONE
, DPCT_NAMED_LAMBDA
and
DPCT_COMPATIBILITY_TEMP
.
Note
Do not manually define these macros. They are automatically defined by
the Intel® DPC++ Compatibility Tool according to the options specified in the
dpct
command line.
|
If the |
|
If the |
|
|
Atomic Helper Functions¶
The atomic helper functions are available in the atomic.hpp
header file. Atomic helper functions are wrappers around standard
SYCL atomic operations.
Device Helper Functions¶
The device helper functions are available in the device.hpp
header file. There
are three classes defined: device_info
, device_ext
and dev_mgr
. Find
more details in the device.hpp
file.
Device Helper Function Classes |
|
---|---|
|
|
|
|
|
|
Helper Functions |
|
---|---|
|
Returns the current device in the device manager. |
|
Returns the default queue associated with the current device in the device manager. |
|
Returns the |
|
Returns the |
|
Returns the SYCL context of the default queue associated with the current device in device manager. |
Memory Helper Functions¶
SYCL Buffer-Based Memory Model Helper Functions |
|
---|---|
Device Memory Manager ( |
Device memory manager is a singleton, intended to assist with migration
of memory API calls if a SYCL buffer-based memory model is used. It provides
API to allocate and free host virtual address space bound to
|
Helper Functions to Get SYCL Buffer From the Host Virtual Address |
|
---|---|
|
Where |
|
Where |
General Helper Functions
General memory helper functions are used to assist the migration
of memory API calls, like memory allocation, memory copy, and
memory set, for both USM and buffer-based memory model. The helper
functions are listed below. Find more details in the
memory.hpp
file.
dpct_malloc()
dpct_free()
dpct_memcpy()
async_dpct_memcpy()
dpct_memset()
async_dpct_memset()
Helper Functions Assisting Migration of Device Memory Variables
To assist with migration of variables declared with global and constant device memory attributes, the helper functions provide the following template classes:
|
Represents a SYCL global memory variable. |
|
Represents a SYCL constant memory variable. |
|
Represents memory that can be accessed by host and device, in the same way as DPC++ USM shared memory. |
Main Member Functions of Memory Classes |
|
---|---|
|
Returns memory pointer of the memory object. It is a virtual pointer when buffer-based memory model is used, and it is a device pointer when a USM memory model is used. |
|
Returns the size of a memory object. |
|
Returns the accessor to the memory object. If a USM memory model is used,
this function returns a |
|
Allocates memory after a SYCL device is selected, and initializes device memory if it has initial value. This API should be called after the SYCL device is selected. |
Kernel Helper Functions¶
Kernel helper functions provide a structure kernel_function_info
to keep
DPC++ kernel information, and provide a utility function get_kernel_function_info()
to get the kernel information.
Image Helper Functions¶
The image helper functions provide class wrappers to assist the migration of
texture API. Find more details on image helper functions in the image.hpp
file.
template class |
The wrapper of |
class |
Wraps SYCL sampler and SYCL image accessor together. Provides the |
class |
Represents the data used to create a
|
class |
Represents 2D/3D matrix data for an image. It contains the image channel information, dimensions, size of each dimension, and the raw data pointer. |
class |
Represents the 2D/3D pitched data for an image. |
struct |
Keeps image channel information; including order, data width, and type information. |
class |
Image sampling information; including addressing mode, filtering mode, and normalization mode. |
|
Creates an object of the helper image class according to the parameters provided. |
Intel® oneAPI DPC++ Library Specific Utility Helper functions¶
The helper functions provided by the header files included in dpl_utils.hpp
include algorithm functions, memory functions, iterators, and a container for
managing data on a device.
Algorithm Helper Functions¶
The algorithm helper functions are available in the dpl_extras/algorithm.h
header file. Algorithm helper functions are wrappers around Intel® oneAPI DPC++ Library (oneDPL) algorithm
functions.
Mask-predicated Algorithm Functions
Mask-predicated algorithm functions have parameter lists like the algorithms with the same name in the C++ standard library. These functions accept an additional iterator pointing to a set of values that indicate whether the corresponding elements of the other inputs to the function should be processed by the algorithm. The predicate provided to these functions is applied to a value in the mask, rather than the element of the input data, and if the predicate returns true the corresponding element of the input data is manipulated by the algorithm.
The mask-predicated algorithm functions in the dpl_extras/algorithm.h
header
file are:
copy_if
partition
partition_copy
remove_if
remove_copy_if
replace_if
replace_copy_if
stable_partition_copy
stable_partition
transform_if
Key-value Pair Algorithm Functions
Key-value pair algorithm functions have parameter lists like the algorithms with
the same name in the C++ standard library. The functions accept two sets of
input data instead of one: the first representing a set of keys and the second
representing the set of values associated with each key. These algorithm functions
create zip_iterators
and invoke the standard algorithm provided in oneDPL so
that the key-value pairs are processed as single data elements.
The key-value pair algorithm functions in the dpl_extras/algorithm.h
header
file are:
unique
unique_copy
merge
sort
stable_sort
set_difference
set_intersection
set_symmetric_difference
set_union
Additional Algorithm Functions
|
Implementation of the C++ standard library algorithm that accepts an execution policy, enabling parallel execution. |
|
Applies a unary operation to every element in the input for which the predicate provided returns true. A mask-predicated version of the function is also provided. |
|
Extends the C++ standard library algorithm by accepting a step in addition to the input iterators and initial value. The step is used to compute the next value in the sequence generated. |
|
Implementation of the C++ standard library algorithm that accepts an execution policy, enabling parallel execution. The binary operation provided for reduction must be associative and commutative. |
|
Assigns each element in the input range provided the result of the unary operator invoked with the element’s index in the input range. |
Memory Helper Functions¶
The dpl_extras/memory.h
header file provides classes and functions for working
with device memory.
Memory Helper Function Classes |
|
---|---|
|
Pointer type that points to memory stored on a device. |
|
Iterator type returned by |
|
Reference type returned by |
The device_vector
implementation that uses the device_iterator
and
device_reference
classes is defined in dpl_extras/vector.h
.
Memory Helper Functions |
|
---|---|
|
Allocates memory for use on a device. |
|
Deallocates memory allocated with |
|
Allocates memory for use on a device large enough to hold the requested number of elements of the type specified. |
|
Deallocates memory allocated using |
|
Constructs a |
|
Returns a raw pointer from a |
Additional oneAPI DPC++ Library Specific Utility Header Files¶
|
Contains the implementation of the function objects used in the definitions of the algorithm functions described above. |
|
Provides an implementation of |
|
Provides an implementation of |
Utility Helper Functions¶
|
Common utility helper functions. |
|
BLAS-specific utility helper functions. |