#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, RT::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...

RT::PiProgram &	getHandleRef ()

const RT::PiProgram &	getHandleRef () const

bool	is_host () const

void	compile_with_kernel_name (std::string KernelName, std::string CompileOptions, OSModuleHandle Module)
	Compiles the SYCL kernel function into the encapsulated raw program. More...

void	compile_with_source (std::string KernelSource, std::string CompileOptions="")
	Compiles the OpenCL C kernel function defined by source string. More...

void	build_with_kernel_name (std::string KernelName, std::string BuildOptions, OSModuleHandle M)
	Builds the SYCL kernel function into encapsulated raw program. More...

void	build_with_source (std::string KernelSource, std::string BuildOptions="")
	Builds the OpenCL C kernel function defined by source code. 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 plugin &	getPlugin () const

std::vector< device >	get_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	set_spec_constant_impl (const char Name, const void ValAddr, size_t ValSize)

void	flush_spec_constants (const RTDeviceBinaryImage &Img, RT::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...

OSModuleHandle	getOSModuleHandle () const
	Returns the OS module handle this program belongs to. 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 38 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

Context	is a pointer to SYCL context impl.
PropList	is an instance of property_list.

Definition at line 30 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

Context	is a pointer to SYCL context impl.
DeviceList	is a list of SYCL devices.
PropList	is an instance of property_list.

Definition at line 35 of file program_impl.cpp.

References sycl::_V1::feature_not_supported.

◆ 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

ProgramList	is a list of program_impl instances.
LinkOptions	is a string containing valid OpenCL link options.
PropList	is an instance of property_list.

Definition at line 47 of file program_impl.cpp.

References sycl::_V1::detail::plugin::call_nocheck(), sycl::_V1::detail::plugin::checkPiResult(), sycl::_V1::detail::compiled, sycl::_V1::feature_not_supported, 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

Context	is a pointer to SYCL context impl.
InteropProgram	is 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,
		RT::PiKernel	Kernel
	)

Constructs a program instance from plugin interface interoperability kernel.

Parameters

Context	is a pointer to SYCL context impl.
Kernel	is 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 208 of file program_impl.cpp.

References sycl::_V1::detail::plugin::call(), 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,
		OSModuleHandle	M
	)

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

KernelName	is a string containing SYCL kernel name.
BuildOptions	is a string containing OpenCL compile options.
M	is an OS handle to user code module.

Definition at line 255 of file program_impl.cpp.

References sycl::_V1::detail::plugin::call(), get_context(), get_devices(), sycl::_V1::detail::ProgramManager::getBuiltPIProgram(), sycl::_V1::detail::ProgramManager::getInstance(), getPlugin(), sycl::_V1::detail::getSyclObjImpl(), is_host(), sycl::_V1::detail::linked, sycl::_V1::detail::none, and piProgramRetain().

◆ build_with_source()

void sycl::_V1::detail::program_impl::build_with_source	(	std::string	KernelSource,
		std::string	BuildOptions = `""`
	)

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

KernelSource	is a string containing OpenCL C kernel source code.
BuildOptions	is a string containing OpenCL build options.

Definition at line 274 of file program_impl.cpp.

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

◆ compile_with_kernel_name()

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

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

KernelName	is a string containing SYCL kernel name.
CompileOptions	is a string of valid OpenCL compile options.
Module	is an OS handle to user code module.

Definition at line 227 of file program_impl.cpp.

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

◆ compile_with_source()

void sycl::_V1::detail::program_impl::compile_with_source	(	std::string	KernelSource,
		std::string	CompileOptions = `""`
	)

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

KernelSource	is a string containing OpenCL C kernel source code.
CompileOptions	is a string containing OpenCL compile options.

Definition at line 242 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,
		RT::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

Img	device binary image corresponding to this program, used to resolve spec constant name to SPIR-V integer ID
NativePrg	if not null, used as the flush target, otherwise MProgram is used

Definition at line 525 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 216 of file program_impl.cpp.

References sycl::_V1::detail::plugin::call(), 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 359 of file program_impl.cpp.

References sycl::_V1::detail::plugin::call(), 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 304 of file program_impl.hpp.

Referenced by sycl::_V1::detail::ProgramManager::getBuiltPIProgram(), and sycl::_V1::detail::ProgramManager::getOrCreateKernel().

◆ 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 278 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 253 of file program_impl.hpp.

Referenced by build_with_kernel_name(), and 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 266 of file program_impl.hpp.

Referenced by build_with_kernel_name().

◆ 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 342 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 294 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 119 of file program_impl.hpp.

◆ get_state()

program_state sycl::_V1::detail::program_impl::get_state ( ) const

inline

Returns: the current state of this SYCL program.

Definition at line 307 of file program_impl.hpp.

◆ getHandleRef() [1/2]

RT::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 134 of file program_impl.hpp.

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

◆ getHandleRef() [2/2]

const RT::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 137 of file program_impl.hpp.

◆ getNative()

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

Returns the native plugin handle.

Definition at line 563 of file program_impl.cpp.

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

◆ getOSModuleHandle()

OSModuleHandle sycl::_V1::detail::program_impl::getOSModuleHandle ( ) const

inline

Returns the OS module handle this program belongs to.

A program belongs to an OS module if it was built from device image(s) belonging to that module. TODO Some programs can be linked from images belonging to different modules. May need a special fake handle for the resulting program.

Definition at line 328 of file program_impl.hpp.

◆ getPlugin()

const plugin& sycl::_V1::detail::program_impl::getPlugin ( ) const

inline

Returns: the Plugin associated with the context of this program.

Definition at line 260 of file program_impl.hpp.

Referenced by build_with_kernel_name(), 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 314 of file program_impl.cpp.

References sycl::_V1::detail::plugin::call_nocheck(), Device, 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 109 of file program_impl.hpp.

◆ hasSetSpecConstants()

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

inline

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

Definition at line 335 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 338 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 140 of file program_impl.hpp.

Referenced by build_with_kernel_name(), build_with_source(), compile_with_kernel_name(), compile_with_source(), get(), get_binaries(), get_kernel(), has_kernel(), link(), program_impl(), and ~program_impl().

◆ isInterop()

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

inline

Definition at line 343 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

LinkOptions is a string containing OpenCL link options.

Definition at line 287 of file program_impl.cpp.

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

◆ set_spec_constant_impl()

void sycl::_V1::detail::program_impl::set_spec_constant_impl	(	const char *	Name,
		const void *	ValAddr,
		size_t	ValSize
	)

Definition at line 514 of file program_impl.cpp.

References sycl::_V1::detail::none, and sycl::_V1::detail::spec_constant_impl::set().

◆ stableSerializeSpecConstRegistry()

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

inline

Definition at line 330 of file program_impl.hpp.

References sycl::_V1::detail::stableSerializeSpecConstRegistry().

Referenced by sycl::_V1::detail::ProgramManager::getBuiltPIProgram(), and sycl::_V1::detail::ProgramManager::getOrCreateKernel().

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

source/detail/program_impl.hpp
source/detail/program_impl.cpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ program_impl() [1/6]

◆ program_impl() [2/6]

◆ program_impl() [3/6]

◆ program_impl() [4/6]

◆ program_impl() [5/6]

◆ program_impl() [6/6]

◆ ~program_impl()

Member Function Documentation

◆ build_with_kernel_name()

◆ build_with_source()

◆ compile_with_kernel_name()

◆ compile_with_source()

◆ flush_spec_constants()

◆ get()

◆ get_binaries()

◆ get_build_options()

◆ get_compile_options()

◆ get_context()

◆ get_devices()

◆ get_kernel()

◆ get_link_options()

◆ get_property()

◆ get_state()

◆ getHandleRef() [1/2]

◆ getHandleRef() [2/2]

◆ getNative()

◆ getOSModuleHandle()

◆ getPlugin()

◆ has_kernel()

◆ has_property()

◆ hasSetSpecConstants()

◆ is_cacheable()

◆ is_host()

◆ isInterop()

◆ link()

◆ set_spec_constant_impl()

◆ stableSerializeSpecConstRegistry()