DPC++ Runtime
Runtime libraries for oneAPI DPC++
sycl::_V1::detail::program_impl Class Reference

#include <detail/program_impl.hpp>

Public Member Functions

 program_impl ()=delete
 
 program_impl (ContextImplPtr Context, const property_list &PropList)
 Constructs an instance of program. More...
 
 program_impl (ContextImplPtr Context, std::vector< device > DeviceList, const property_list &PropList)
 Constructs an instance of SYCL program for the provided DeviceList. More...
 
 program_impl (std::vector< std::shared_ptr< program_impl >> ProgramList, std::string LinkOptions, const property_list &PropList)
 Constructs an instance of SYCL program by linking together each SYCL program instance in ProgramList. More...
 
 program_impl (ContextImplPtr Context, pi_native_handle InteropProgram)
 Constructs a program instance from an interop raw BE program handle. More...
 
 program_impl (ContextImplPtr Context, sycl::detail::pi::PiKernel Kernel)
 Constructs a program instance from plugin interface interoperability kernel. More...
 
 ~program_impl ()
 
template<typename propertyT >
bool has_property () const
 Checks if this program_impl has a property of type propertyT. More...
 
template<typename propertyT >
propertyT get_property () const
 Gets the specified property of this program_impl. More...
 
cl_program get () const
 Returns a valid cl_program instance. More...
 
sycl::detail::pi::PiProgramgetHandleRef ()
 
const sycl::detail::pi::PiProgramgetHandleRef () const
 
bool is_host () const
 
void compile_with_kernel_name (std::string KernelName, std::string CompileOptions)
 Compiles the SYCL kernel function into the encapsulated raw program. More...
 
void build_with_kernel_name (std::string KernelName, std::string BuildOptions)
 Builds the SYCL kernel function into encapsulated raw program. More...
 
void link (std::string LinkOptions="")
 Links encapsulated raw program. More...
 
bool has_kernel (std::string KernelName, bool IsCreatedFromSource) const
 Checks if kernel is available for this program. More...
 
kernel get_kernel (std::string KernelName, std::shared_ptr< program_impl > PtrToSelf, bool IsCreatedFromSource) const
 Returns a SYCL kernel for the SYCL kernel function defined by kernel name. More...
 
std::vector< std::vector< char > > get_binaries () const
 Returns built program binaries. More...
 
context get_context () const
 
const PluginPtrgetPlugin () const
 
ContextImplPtr getContextImplPtr () const
 
std::vector< deviceget_devices () const
 
std::string get_compile_options () const
 Returns compile options that were provided when the encapsulated program was explicitly compiled. More...
 
std::string get_link_options () const
 Returns compile options that were provided to the most recent invocation of link member function. More...
 
std::string get_build_options () const
 Returns the compile, link, or build options, from whichever of those operations was performed most recently on the encapsulated cl_program. More...
 
program_state get_state () const
 
void flush_spec_constants (const RTDeviceBinaryImage &Img, sycl::detail::pi::PiProgram NativePrg=nullptr) const
 Takes current values of specialization constants and "injects" them into the underlying native program program via specialization constant managemment PI APIs. More...
 
void stableSerializeSpecConstRegistry (SerializedObj &Dst) const
 
bool hasSetSpecConstants () const
 Tells whether a specialization constant has been set for this program. More...
 
bool is_cacheable () const
 
pi_native_handle getNative () const
 Returns the native plugin handle. More...
 
bool isInterop () const
 

Detailed Description

Definition at line 37 of file program_impl.hpp.

Constructor & Destructor Documentation

◆ program_impl() [1/6]

sycl::_V1::detail::program_impl::program_impl ( )
delete

◆ program_impl() [2/6]

sycl::_V1::detail::program_impl::program_impl ( ContextImplPtr  Context,
const property_list PropList 
)
explicit

Constructs an instance of program.

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

Parameters
Contextis a pointer to SYCL context impl.
PropListis an instance of property_list.

Definition at line 29 of file program_impl.cpp.

◆ program_impl() [3/6]

sycl::_V1::detail::program_impl::program_impl ( ContextImplPtr  Context,
std::vector< device DeviceList,
const property_list PropList 
)

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 devices in the provided DeviceList.

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

Definition at line 34 of file program_impl.cpp.

◆ program_impl() [4/6]

sycl::_V1::detail::program_impl::program_impl ( std::vector< std::shared_ptr< program_impl >>  ProgramList,
std::string  LinkOptions,
const property_list PropList 
)

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

Each 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. Kernels caching for linked programs won't be allowed due to only compiled state of each and every program in the list and thus unknown state of caching resolution.

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

Definition at line 46 of file program_impl.cpp.

References sycl::_V1::detail::compiled, getPlugin(), is_host(), sycl::_V1::detail::linked, and piProgramLink().

◆ program_impl() [5/6]

sycl::_V1::detail::program_impl::program_impl ( ContextImplPtr  Context,
pi_native_handle  InteropProgram 
)

Constructs a program instance from an interop raw BE program handle.

TODO: BE generalization will change that to something better.

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

The instance of the program will be retained on construction.

Parameters
Contextis a pointer to SYCL context impl.
InteropProgramis an instance of plugin interface interoperability program.

Definition at line 119 of file program_impl.cpp.

◆ program_impl() [6/6]

sycl::_V1::detail::program_impl::program_impl ( ContextImplPtr  Context,
sycl::detail::pi::PiKernel  Kernel 
)

Constructs a program instance from plugin interface interoperability kernel.

Parameters
Contextis a pointer to SYCL context impl.
Kernelis a raw PI kernel handle.

Definition at line 201 of file program_impl.cpp.

◆ ~program_impl()

sycl::_V1::detail::program_impl::~program_impl ( )

Definition at line 209 of file program_impl.cpp.

References getPlugin(), is_host(), and piProgramRelease().

Member Function Documentation

◆ build_with_kernel_name()

void sycl::_V1::detail::program_impl::build_with_kernel_name ( std::string  KernelName,
std::string  BuildOptions 
)

Builds the SYCL kernel function into encapsulated raw program.

The SYCL kernel function is defined by the kernel name. 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
KernelNameis a string containing SYCL kernel name.
BuildOptionsis a string containing OpenCL compile options.
Mis an OS handle to user code module.

◆ compile_with_kernel_name()

void sycl::_V1::detail::program_impl::compile_with_kernel_name ( std::string  KernelName,
std::string  CompileOptions 
)

Compiles the SYCL kernel function into the encapsulated raw program.

The kernel function is defined by its name. 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
KernelNameis a string containing SYCL kernel name.
CompileOptionsis a string of valid OpenCL compile options.
Moduleis an OS handle to user code module.

Definition at line 228 of file program_impl.cpp.

References sycl::_V1::detail::compiled, is_host(), and sycl::_V1::detail::none.

◆ flush_spec_constants()

void sycl::_V1::detail::program_impl::flush_spec_constants ( const RTDeviceBinaryImage Img,
sycl::detail::pi::PiProgram  NativePrg = nullptr 
) const

Takes current values of specialization constants and "injects" them into the underlying native program program via specialization constant managemment PI APIs.

The native program passed as non-null argument overrides the MProgram native program field.

Parameters
Imgdevice binary image corresponding to this program, used to resolve spec constant name to SPIR-V integer ID
NativePrgif not null, used as the flush target, otherwise MProgram is used

Definition at line 446 of file program_impl.cpp.

References sycl::_V1::detail::DeviceBinaryProperty::asByteArray(), sycl::_V1::detail::ByteArray::consume(), sycl::_V1::detail::ByteArray::dropBytes(), sycl::_V1::detail::ByteArray::empty(), get_context(), getHandleRef(), sycl::_V1::detail::RTDeviceBinaryImage::getSpecConstants(), sycl::_V1::detail::getSyclObjImpl(), sycl::_V1::detail::spec_constant_impl::getValuePtr(), sycl::_V1::detail::spec_constant_impl::isSet(), and piextProgramSetSpecializationConstant().

Referenced by sycl::_V1::detail::ProgramManager::flushSpecConstants().

◆ get()

cl_program sycl::_V1::detail::program_impl::get ( ) const

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.

Definition at line 217 of file program_impl.cpp.

References getPlugin(), is_host(), sycl::_V1::detail::none, and piProgramRetain().

Referenced by sycl::_V1::detail::ProgramManager::flushSpecConstants().

◆ get_binaries()

std::vector< std::vector< char > > sycl::_V1::detail::program_impl::get_binaries ( ) const

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.

Definition at line 315 of file program_impl.cpp.

References getPlugin(), is_host(), sycl::_V1::detail::none, PI_PROGRAM_INFO_BINARIES, PI_PROGRAM_INFO_BINARY_SIZES, and piProgramGetInfo().

◆ get_build_options()

std::string sycl::_V1::detail::program_impl::get_build_options ( ) const
inline

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.

Definition at line 271 of file program_impl.hpp.

◆ get_compile_options()

std::string sycl::_V1::detail::program_impl::get_compile_options ( ) const
inline

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.

Definition at line 245 of file program_impl.hpp.

◆ get_context()

context sycl::_V1::detail::program_impl::get_context ( ) const
inline
Returns
the SYCL context that this program was constructed with.

Definition at line 218 of file program_impl.hpp.

References is_host().

Referenced by flush_spec_constants().

◆ get_devices()

std::vector<device> sycl::_V1::detail::program_impl::get_devices ( ) const
inline
Returns
a vector of devices that are associated with this program.

Definition at line 233 of file program_impl.hpp.

◆ get_kernel()

kernel sycl::_V1::detail::program_impl::get_kernel ( std::string  KernelName,
std::shared_ptr< program_impl PtrToSelf,
bool  IsCreatedFromSource 
) const

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

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.

Definition at line 298 of file program_impl.cpp.

References is_host(), and sycl::_V1::detail::none.

◆ get_link_options()

std::string sycl::_V1::detail::program_impl::get_link_options ( ) const
inline

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.

Definition at line 261 of file program_impl.hpp.

◆ get_property()

template<typename propertyT >
propertyT sycl::_V1::detail::program_impl::get_property ( ) const
inline

Gets the specified property of this program_impl.

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

Returns
a copy of the property of type propertyT.

Definition at line 118 of file program_impl.hpp.

References sycl::_V1::property_list::get_property().

◆ get_state()

program_state sycl::_V1::detail::program_impl::get_state ( ) const
inline
Returns
the current state of this SYCL program.

Definition at line 274 of file program_impl.hpp.

◆ getContextImplPtr()

ContextImplPtr sycl::_V1::detail::program_impl::getContextImplPtr ( ) const
inline

Definition at line 230 of file program_impl.hpp.

Referenced by getNative().

◆ getHandleRef() [1/2]

sycl::detail::pi::PiProgram& sycl::_V1::detail::program_impl::getHandleRef ( )
inline
Returns
a reference to a raw PI program handle. PI program is not retained before return.

Definition at line 133 of file program_impl.hpp.

Referenced by flush_spec_constants(), and sycl::_V1::detail::ProgramManager::flushSpecConstants().

◆ getHandleRef() [2/2]

const sycl::detail::pi::PiProgram& sycl::_V1::detail::program_impl::getHandleRef ( ) const
inline
Returns
a constant reference to a raw PI program handle. PI program is not retained before return.

Definition at line 136 of file program_impl.hpp.

◆ getNative()

pi_native_handle sycl::_V1::detail::program_impl::getNative ( ) const

Returns the native plugin handle.

Definition at line 485 of file program_impl.cpp.

References getContextImplPtr(), getPlugin(), sycl::_V1::opencl, piextProgramGetNativeHandle(), and piProgramRetain().

◆ getPlugin()

const PluginPtr& sycl::_V1::detail::program_impl::getPlugin ( ) const
inline
Returns
the Plugin associated with the context of this program.

Definition at line 225 of file program_impl.hpp.

References is_host().

Referenced by get(), get_binaries(), getNative(), has_kernel(), link(), program_impl(), and ~program_impl().

◆ has_kernel()

bool sycl::_V1::detail::program_impl::has_kernel ( std::string  KernelName,
bool  IsCreatedFromSource 
) const

Checks if kernel is available for this program.

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

Returns
true if the SYCL kernel is available.

Definition at line 270 of file program_impl.cpp.

References getPlugin(), is_host(), sycl::_V1::detail::none, and piextGetDeviceFunctionPointer().

◆ has_property()

template<typename propertyT >
bool sycl::_V1::detail::program_impl::has_property ( ) const
inline

Checks if this program_impl has a property of type propertyT.

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

Definition at line 108 of file program_impl.hpp.

References sycl::_V1::property_list::has_property().

◆ hasSetSpecConstants()

bool sycl::_V1::detail::program_impl::hasSetSpecConstants ( ) const
inline

Tells whether a specialization constant has been set for this program.

Definition at line 293 of file program_impl.hpp.

Referenced by sycl::_V1::detail::ProgramManager::flushSpecConstants().

◆ is_cacheable()

bool sycl::_V1::detail::program_impl::is_cacheable ( ) const
inline
Returns
true if caching is allowed for this program.

Definition at line 296 of file program_impl.hpp.

◆ is_host()

bool sycl::_V1::detail::program_impl::is_host ( ) const
inline
Returns
true if this SYCL program is a host program.

Definition at line 139 of file program_impl.hpp.

Referenced by compile_with_kernel_name(), get(), get_binaries(), get_context(), get_kernel(), getPlugin(), has_kernel(), link(), program_impl(), and ~program_impl().

◆ isInterop()

bool sycl::_V1::detail::program_impl::isInterop ( ) const
inline

Definition at line 301 of file program_impl.hpp.

◆ link()

void sycl::_V1::detail::program_impl::link ( std::string  LinkOptions = "")

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.

Definition at line 241 of file program_impl.cpp.

References sycl::_V1::detail::compiled, sycl::_V1::detail::SYCLConfig< Config >::get(), getPlugin(), is_host(), sycl::_V1::detail::linked, piProgramLink(), and piProgramRelease().

◆ stableSerializeSpecConstRegistry()

void sycl::_V1::detail::program_impl::stableSerializeSpecConstRegistry ( SerializedObj Dst) const
inline

The documentation for this class was generated from the following files: