DPC++ Runtime
Runtime libraries for oneAPI Data Parallel C++
DPC++ User API
Collaboration diagram for DPC++ User API:

Modules

 Device selectors
 Device selectors enable DPC++ runtime to choose the best devices based on heuristics specified by the user, or by one of the built-in selectors.
 
 Accessors
 Specify aquisition and release of buffer and image data structures.
 

Classes

class  cl::sycl::buffer< T, dimensions, AllocatorT, typename >
 Defines a shared array that can be used by kernels in queues. More...
 
class  cl::sycl::context
 The context class represents a SYCL context on which kernel functions may be executed. More...
 
class  cl::sycl::device
 The SYCL device class encapsulates a single SYCL device on which kernels may be executed. More...
 
class  cl::sycl::device_event
 Encapsulates a single SYCL device event which is available only within SYCL kernel functions and can be used to wait for asynchronous operations within a kernel function to complete. More...
 
class  cl::sycl::event
 An event object can be used to synchronize memory transfers, enqueues of kernels and signaling barriers. More...
 
class  cl::sycl::exception
 
class  cl::sycl::exception_list
 A list of asynchronous exceptions. More...
 
class  cl::sycl::group< Dimensions >
 Encapsulates all functionality required to represent a particular work-group within a parallel execution. More...
 
class  cl::sycl::h_item< dimensions >
 Identifies an instance of a group::parallel_for_work_item function object executing at each point in a local range passed to a parallel_for_work_item call or to the corresponding parallel_for_work_group call. More...
 
class  cl::sycl::handler
 Command group handler class. More...
 
class  cl::sycl::id< dimensions >
 A unique identifier of an item in an index space. More...
 
class  cl::sycl::image< Dimensions, AllocatorT >
 Defines a shared image data. More...
 
class  cl::sycl::item< dimensions, with_offset >
 Identifies an instance of the function object executing at each point in a range. More...
 
class  cl::sycl::kernel
 Provides an abstraction of a SYCL kernel. More...
 
class  cl::sycl::kernel_id
 Objects of the class identify kernel is some kernel_bundle related APIs. More...
 
class  cl::sycl::kernel_bundle< State >
 The kernel_bundle class represents collection of device images in a particular state. More...
 
class  cl::sycl::kernel_handler
 Reading the value of a specialization constant. More...
 
class  cl::sycl::marray< Type, NumElements >
 Provides a cross-patform math array class template that works on SYCL devices as well as in host C++ code. More...
 
class  cl::sycl::multi_ptr< ElementType, Space >
 Provides constructors for address space qualified and non address space qualified pointers to allow interoperability between plain C++ and OpenCL C. More...
 
class  cl::sycl::nd_item< dimensions >
 Identifies an instance of the function object executing at each point in an nd_range. More...
 
class  cl::sycl::nd_range< dimensions >
 Defines the iteration domain of both the work-groups and the overall dispatch. More...
 
class  cl::sycl::platform
 Encapsulates a SYCL platform on which kernels may be executed. More...
 
class  cl::sycl::property_list
 Objects of the property_list class are containers for the SYCL properties. More...
 
class  cl::sycl::queue
 Encapsulates a single SYCL queue which schedules kernels on a SYCL device. More...
 
class  cl::sycl::range< dimensions >
 Defines the iteration domain of either a single work-group in a parallel dispatch, or the overall dimensions of the dispatch. More...
 
class  cl::sycl::sampler
 Encapsulates a configuration for sampling an image accessor. More...
 
class  cl::sycl::specialization_id< T >
 Declaring a specialization constant. More...
 
class  cl::sycl::stream
 A buffered output stream that allows outputting the values of built-in, vector and SYCL types to the console. More...
 
class  cl::sycl::vec< Type, NumElements >
 Provides a cross-patform vector class template that works efficiently on SYCL devices as well as in host C++ code. More...
 
class  cl::sycl::ext::oneapi::accessor_property_list< PropsT >
 Objects of the accessor_property_list class are containers for the SYCL properties. More...
 

Functions

class cl::sycl::__SYCL2020_DEPRECATED ("program class is deprecated, use kernel_bundle instead") program
 Provides an abstraction of a SYCL program. More...
 

Detailed Description

Todo:
a more specific intro

A sample DPC++ application:

#include <CL/sycl.hpp>
using namespace cl::sycl;
int main() {
// Create a buffer of 4 ints to be used inside the kernel code.
buffer<int, 1> Buffer(4);
// Create a simple asynchronous exception handler.
auto AsyncHandler = [](exception_list ExceptionList) {
for (auto &Exception : ExceptionList) {
std::rethrow_exception(Exception);
}
};
// Create a SYCL queue.
queue Queue(AsyncHandler);
// Size of index space for kernel.
range<1> NumOfWorkItems{Buffer.size()};
// Submit command group(work) to queue.
Queue.submit([&](handler &cgh) {
// Get write only access to the buffer on a device.
auto Accessor = Buffer.get_access<access::mode::write>(cgh);
// Execute kernel.
cgh.parallel_for<class FillBuffer>(NumOfWorkItems, [=](id<1> WIid) {
// Fill buffer with indices.
Accessor[WIid] = static_cast<int>(WIid.get(0));
});
});
// Get read only access to the buffer on the host.
// This introduces an implicit barrier which blocks execution until the
// command group above completes.
const auto HostAccessor = Buffer.get_access<access::mode::read>();
// Check the results.
bool MismatchFound = false;
for (size_t I = 0; I < Buffer.size(); ++I) {
if (HostAccessor[I] != I) {
std::cout << "The result is incorrect for element: " << I
<< " , expected: " << I << " , got: " << HostAccessor[I]
<< std::endl;
MismatchFound = true;
}
}
if (!MismatchFound) {
std::cout << "The results are correct!" << std::endl;
}
return MismatchFound;
}

Function Documentation

◆ __SYCL2020_DEPRECATED()

class cl::sycl::__SYCL2020_DEPRECATED ( "program class is  deprecated,
use kernel_bundle instead  
)

Provides an abstraction of a SYCL program.

See also
kernel
queue

Constructs an instance of SYCL program.

The program will be created in the program_state::none state and associated with the provided context and the SYCL devices that are associated with the context.

Parameters
Contextis an instance of SYCL context.
PropListis an instance of property_list.

Constructs an instance of SYCL program for the provided DeviceList.

The program will be created in the program_state::none state and associated with the provided context and the SYCL devices in the provided DeviceList.

Parameters
Contextis an instance of SYCL context.
DeviceListis a list of SYCL devices.
PropListis an instance of property_list.

Constructs an instance of SYCL program by linking together each SYCL program instance in ProgramList.

Each SYCL program in ProgramList must be in the program_state::compiled state and must be associated with the same SYCL context. Otherwise an invalid_object_error SYCL exception will be thrown. A feature_not_supported exception will be thrown if any device that the program is to be linked for returns false for the device information query info::device::is_linker_available.

Parameters
ProgramListis a list of SYCL program instances.
PropListis an instance of property_list.

Constructs an instance of SYCL program by linking together each SYCL program instance in ProgramList.

Each SYCL program in ProgramList must be in the program_state::compiled state and must be associated with the same SYCL context. Otherwise an invalid_object_error SYCL exception will be thrown. A feature_not_supported exception will be thrown if any device that the program is to be linked for returns false for the device information query info::device::is_linker_available.

Parameters
ProgramListis a list of SYCL program instances.
LinkOptionsis a string containing valid OpenCL link options.
PropListis an instance of property_list.

Constructs a SYCL program instance from an OpenCL cl_program.

The state of the constructed SYCL program can be either program_state::compiled or program_state::linked, depending on the state of the ClProgram. Otherwise an invalid_object_error SYCL exception is thrown.

The instance of OpenCL cl_program will be retained on construction.

Parameters
Contextis an instance of SYCL Context.
ClProgramis an instance of OpenCL cl_program.

Checks if this program has a property of type propertyT.

Returns
true if this context has a property of type propertyT.

Gets the specified property of this program.

Throws invalid_object_error if this program does not have a property of type propertyT.

Returns
a copy of the property of type propertyT.

Returns a valid cl_program instance.

The instance of cl_program will be retained before returning. If the program is created for a SYCL host device, an invalid_object_error exception is thrown.

Returns
a valid OpenCL cl_program instance.
true if this SYCL program is a host program.

Compiles the SYCL kernel function into the encapsulated raw program.

The kernel function is defined by the type KernelT. This member function sets the state of this SYCL program to program_state::compiled. If this program was not in the program_state::none state, an invalid_object_error exception is thrown. If the compilation fails, a compile_program_error SYCL exception is thrown. If any device that the program is being compiled for returns false for the device information query info::device::is_compiler_available, a feature_not_supported exception is thrown.

Parameters
CompileOptionsis a string of valid OpenCL compile options.

Compiles the OpenCL C kernel function defined by source string.

This member function sets the state of this SYCL program to program_state::compiled. If the program was not in the program_state::none state, an invalid_object_error SYCL exception is thrown. If the compilation fails, a compile_program_error SYCL exception is thrown. If any device that the program is being compiled for returns false for the device information query info::device::is_compiler_available, a feature_not_supported SYCL exception is thrown.

Parameters
KernelSourceis a string containing OpenCL C kernel source code.
CompileOptionsis a string containing OpenCL compile options.

Builds the SYCL kernel function into encapsulated raw program.

The SYCL kernel function is defined by the type KernelT. This member function sets the state of this SYCL program to program_state::linked. If the program was not in the program_state::none state, an invalid_object_error SYCL exception is thrown. If the compilation fails, a compile_program_error SYCL exception is thrown. If any device that the program is being built for returns false for the device information queries info::device::is_compiler_available or info::device::is_linker_available, a feature_not_supported SYCL exception is thrown.

Parameters
BuildOptionsis a string containing OpenCL compile options.

Builds the OpenCL C kernel function defined by source code.

This member function sets the state of this SYCL program to program_state::linked. If this program was not in program_state::none, an invalid_object_error SYCL exception is thrown. If the compilation fails, a compile_program_error SYCL exception is thrown. If any device that the program is being built for returns false for the device information queries info::device::is_compiler_available or info::device::is_linker_available, a feature_not_supported SYCL exception is thrown.

Parameters
KernelSourceis a string containing OpenCL C kernel source code.
BuildOptionsis a string containing OpenCL build options.

Links encapsulated raw program.

This member function sets the state of this SYCL program to program_state::linked. If the program was not in the program_state::compiled state, an invalid_object_error SYCL exception is thrown. If linking fails, a compile_program_error is thrown. If any device that the program is to be linked for returns false for the device information query info::device::is_linker_available, a feature_not_supported exception is thrown.

Parameters
LinkOptionsis a string containing OpenCL link options.

Checks if kernel is available for this program.

The SYCL kernel is defined by type KernelT. If the program state is program_state::none an invalid_object_error SYCL exception is thrown.

Returns
true if the SYCL kernel is available.

Checks if kernel is available for this program.

The SYCL kernel is defined by its name. If the program is in the program_stateP::none state, an invalid_object_error SYCL exception is thrown.

Parameters
KernelNameis a string containing kernel name.
Returns
true if the SYCL kernel is available and the program is not a SYCL host program.

Returns a SYCL kernel for the SYCL kernel function defined by KernelType.

If program is in the program_state::none state or if the SYCL kernel function is not available, an invalid_object_error exception is thrown.

Returns
a valid instance of SYCL kernel.

Returns a SYCL kernel for the SYCL kernel function defined by KernelName.

An invalid_object_error SYCL exception is thrown if this program is a host program, if program is in the program_state::none state or if the SYCL kernel is not available.

Parameters
KernelNameis a string containing SYCL kernel name.

Queries this SYCL program for information.

The return type depends on the information being queried.

Returns built program binaries.

If this program is not in the program_state::compiled or program_state::linked states, an invalid_object_error SYCL exception is thrown.

Returns
a vector of vectors representing the compiled binaries for each associated SYCL device.
the SYCL context that this program was constructed with.
a vector of devices that are associated with this program.

Returns compile options that were provided when the encapsulated program was explicitly compiled.

If the program was built instead of explicitly compiled, if the program has not yet been compiled, or if the program has been compiled for only the host device, then an empty string is return, unless the underlying cl_program was explicitly compiled, in which case the compile options used in the explicit compile are returned.

Returns
a string of valid OpenCL compile options.

Returns compile options that were provided to the most recent invocation of link member function.

If the program has not been explicitly linked using the aforementioned function, constructed with an explicitly linking constructor, or if the program has been linked for only the host device, then an empty string is returned. If the program was constructed from cl_program, then an empty string is returned unless the cl_program was explicitly linked, in which case the link options used in that explicit link are returned. If the program object was constructed using a constructor form that links a vector of programs, then the link options passed to this constructor are returned.

Returns
a string of valid OpenCL compile options.

Returns the compile, link, or build options, from whichever of those operations was performed most recently on the encapsulated cl_program.

If no compile, link, or build operations have been performed on this program, or if the program includes the host device in its device list, then an empty string is returned.

Returns
a string of valid OpenCL build options.
the current state of this SYCL program.

Set the value of the specialization constant identified by the 'ID' type template parameter and return its instance.

Parameters
cstthe specialization constant value
Returns
a specialization constant instance corresponding to given type ID passed as a template parameter

Returns the backend associated with this program.

Returns
the backend associated with this program.

Gets the native handle of the SYCL platform.

Returns
a native handle, the type of which defined by the backend.

Template-free version of get_kernel.

Parameters
KernelNameis a stringified kernel name.
IsCreatedFromSourceis a flag indicating whether this program was created from OpenCL C source code string.
Returns
a valid instance of SYCL kernel.

Template-free version of has_kernel.

Parameters
KernelNameis a stringified kernel name.
IsCreatedFromSourceis a flag indicating whether this program was created from OpenCL C source code string.
Returns
true if kernel with KernelName is available.

Template-free version of compile_with_kernel_type.

Parameters
KernelNameis a stringified kernel name.
CompileOptionsis a string of valid OpenCL compile options.
Mis a valid OS handle to the user executable or library.

Template-free version of build_with_kernel_type.

Parameters
KernelNameis a stringified kernel name.
CompileOptionsis a string of valid OpenCL compile options.
Mis a valid OS handle to the user executable or library.

Definition at line 39 of file program.hpp.

References cl::sycl::detail::createSyclObjFromImpl(), std::get(), cl::sycl::get_native(), cl::sycl::detail::getSyclObjImpl(), cl::sycl::link(), cl::sycl::operator!=(), and operator==().

cl::sycl::access::mode::read
@ read
cl::sycl::id< 1 >
cl::sycl
Definition: access.hpp:14
cl::sycl::queue
Encapsulates a single SYCL queue which schedules kernels on a SYCL device.
Definition: queue.hpp:82
cl::sycl::buffer
Defines a shared array that can be used by kernels in queues.
Definition: buffer.hpp:38
cl::sycl::range< 1 >
cl::sycl::range::size
size_t size() const
Definition: range.hpp:58
cl::sycl::handler::parallel_for
void parallel_for(range< 1 > NumWorkItems, KernelType KernelFunc)
Definition: handler.hpp:1240
sycl.hpp
cl::sycl::handler
Command group handler class.
Definition: handler.hpp:328
cl::sycl::access::mode::write
@ write
cl::sycl::exception_list
A list of asynchronous exceptions.
Definition: exception_list.hpp:30