Public facing program class that provides an interface for abstracting the construction and building of a cl_program object, See section 3.5.5 of the SYCL 1.2 specification. More...

#include <program.h>

Public Member Functions
	program (const context &context, const property_list &propList={})
	Constructs a program for a context. More...

	program (const context &context, vector_class< device > deviceList, const property_list &propList={})
	Constructs a program for a list of devices on a context. More...

	program (const context &context, cl_program clProgram)
	Inter-op constructor that takes a context and a cl_program. More...

	program (vector_class< program > programList, const property_list &propList={})
	Linker constructor from a list of programs. More...

	program (vector_class< program > programList, string_class linkOptions, const property_list &propList={})
	Linker constructor from a list of programs. More...

	program (vector_class< program > programList, const char *linkOptions, const property_list &propList={})

	program (const program &rhs)=default
	Copy constructor that initialises a copy of the program with the same underlying cl_program, associated context and list of associated devices. More...

program &	operator= (const program &rhs)=default
	Assignment operator that initialises a copy of the program with the same underlying cl_program, associated context and list of associated devices. More...

	program (program &&rhs)=default
	Copy constructor that initialises a copy of the program with the same underlying cl_program, associated context and list of associated devices. More...

program &	operator= (program &&rhs)=default
	Assignment operator that initialises a copy of the program with the same underlying cl_program, associated context and list of associated devices. More...

COMPUTECPP_TEST_VIRTUAL	~program ()=default
	Destructor that releases the cl_program. More...

template<typename kernelT >
void	compile_with_kernel_type (string_class compileOptions="")
	Compile a SYCL kernel using name and optional custom compile options. More...

void	compile_with_source (string_class kernelSource, string_class compileOptions="")
	Compiles a program from the given OpenCL C kernel source. More...

void	compile_with_source (const char kernelSrc, const char compileOptions)
	Compiles a program from the given OpenCL C kernel source. More...

void	create_from_built_in_kernel (string_class kernel)
	Creates a valid cl_program from a pre-built kernel provided by the underlying OpenCL implementation. More...

void	create_from_built_in_kernel (const char *kernel)
	Creates a valid cl_program from a pre-built kernel provided by the underlying OpenCL implementation. More...

template<typename kernelT >
void	build_with_kernel_type (string_class buildOptions="")
	Build a SYCL kernel using its name and optional custom build options. More...

void	build_with_source (string_class kernelSource, string_class buildOptions="")
	Creates and builds a program from OpenCL C kernel source and optional build options. More...

void	build_with_source (const char kernelSrc, const char compileOptions)
	Creates and builds a program from OpenCL C kernel source and optional build options. More...

void	link (string_class linkOptions="")
	Link all compiled programs using the (optional) link options. More...

void	link (const char *linkOptions)
	Link all compiled programs using the (optional) link options. More...

template<typename kernelT >
bool	has_kernel () const
	Checks whether the program contains a kernel specified by the type. More...

bool	has_kernel (string_class kernelName) const
	Checks whether the program contains a kernel specified by the name. More...

bool	has_kernel (const char *kernelName) const

template<typename kernelT >
kernel	get_kernel () const
	Retrieve a SYCL kernel object described by the typename kernelT. More...

kernel	get_kernel (string_class kernelName) const
	Retrieve a SYCL kernel object described by the kernel name. More...

kernel	get_kernel (const char *kernelName) const

template<info::program param>
COMPUTECPP_EXPORT info::param_traits< info::program, param >::return_type	get_info () const
	Retrieves information about the program. More...

vector_class< vector_class< char > >	get_binaries () const
	Return the list of binaries that were used to compile and link the program. More...

context	get_context () const
	Retrieves the context associated with the program. More...

vector_class< cl::sycl::device >	get_devices () const
	Return the list of devices associated with the program. More...

string_class	get_compile_options () const
	Return the compile options used when compiling the program. More...

string_class	get_link_options () const
	Return the link options used when linking the program. More...

string_class	get_build_options () const
	Return the build options used when building the program. More...

cl_program	get () const
	Inter-op member function that returns the underlying cl_program. More...

bool	is_linked () const
	Return a bool specifying whether the program has been linked. More...

bool	is_host () const
	Returns whether the program was constructed from a host context. More...

program_state	get_state () const
	Retrieves the current build state of the program. More...

Protected Member Functions
cl_program	get_no_retain () const
	Inter-op member function that returns the underlying cl_program. More...

Static Protected Member Functions
template<typename BIType >
static const BIType &	select_kernel_binary_info_helper (const BIType *binList, size_t binListSize, ddevice_wkptr dev)
	Retrieve an appropriate binary to build a program. More...

template<typename BIType >
static const detail::kernel_binary_info &	select_kernel_binary_info (const detail::kernel_binary_info &hostBinaryInfo, const BIType *binList, size_t binListSize, const context &ctx)
	Retrieves binary info to build a program. More...

Friends
bool	operator== (const program &lhs, const program &rhs)
	Determines if lhs and rhs are equal. More...

bool	operator!= (const program &lhs, const program &rhs)
	Determines if lhs and rhs are not equal. More...

Detailed Description

Public facing program class that provides an interface for abstracting the construction and building of a cl_program object, See section 3.5.5 of the SYCL 1.2 specification.

Definition at line 107 of file program.h.

Constructor & Destructor Documentation

◆ program() [1/8]

cl::sycl::program::program	(	const context &	context,
		const property_list &	propList = `{}`
	)

explicit

Constructs a program for a context.

Parameters

context	The context that will be associated with the program
propList	Additional properties

◆ program() [2/8]

cl::sycl::program::program	(	const context &	context,
		vector_class< device >	deviceList,
		const property_list &	propList = `{}`
	)

Constructs a program for a list of devices on a context.

Parameters

context	The context that will be associated with the program
deviceList	List of devices that will be associated with the program
propList	Additional properties

◆ program() [3/8]

cl::sycl::program::program	(	const context &	context,
		cl_program	clProgram
	)

Inter-op constructor that takes a context and a cl_program.

Note that the clProgram param must have previously been created from the underlying cl_context of the context parameter and the underlying cl_devices from the list of devices parameter.

Parameters

context	A reference to the context that the cl_program will be associated with.
clProgram	The cl_program that the program will be assigned to.

◆ program() [4/8]

cl::sycl::program::program	(	vector_class< program >	programList,
		const property_list &	propList = `{}`
	)

inline

Linker constructor from a list of programs.

All of the provided programs must be in the compiled program state and associated with the same context. The constructed program will be in the linked program state.

Parameters

programList	List of programs to link together into a new program
propList	Additional properties

Exceptions

invalid_object_error if provided programs not associated with the same context or if not all of them are in the compiled program state

Definition at line 152 of file program.h.

◆ program() [5/8]

cl::sycl::program::program	(	vector_class< program >	programList,
		string_class	linkOptions,
		const property_list &	propList = `{}`
	)

inline

Linker constructor from a list of programs.

All of the provided programs must be in the compiled program state and associated with the same context. The constructed program will be in the linked program state.

Parameters

programList	List of programs to link together into a new program
linkOptions	String of options used when linking programs
propList	Additional properties

Exceptions

invalid_object_error if provided programs not associated with the same context or if not all of them are in the compiled program state

Definition at line 168 of file program.h.

◆ program() [6/8]

cl::sycl::program::program	(	vector_class< program >	programList,
		const char *	linkOptions,
		const property_list &	propList = `{}`
	)

All of the provided programs must be in the compiled program state and associated with the same context. The constructed program will be in the linked program state.

Parameters

programList	List of programs to link together into a new program
linkOptions	String of options used when linking programs
propList	Additional properties

Exceptions

invalid_object_error if provided programs not associated with the same context or if not all of them are in the compiled program state

◆ program() [7/8]

cl::sycl::program::program ( const program & rhs )

default

Copy constructor that initialises a copy of the program with the same underlying cl_program, associated context and list of associated devices.

Parameters

rhs	The program being copied from.

◆ program() [8/8]

cl::sycl::program::program ( program && rhs )

default

Copy constructor that initialises a copy of the program with the same underlying cl_program, associated context and list of associated devices.

Parameters

rhs	The program being copied from.

◆ ~program()

COMPUTECPP_TEST_VIRTUAL cl::sycl::program::~program ( )

default

Destructor that releases the cl_program.

Member Function Documentation

◆ build_with_kernel_type()

template<typename kernelT >

void cl::sycl::program::build_with_kernel_type ( string_class buildOptions = "" )

inline

Build a SYCL kernel using its name and optional custom build options.

This function produces a ready-to-run program. Note that calling this member function is invalid if the program has already been successfully compiled, built or linked via either link(string_class), compile_with_kernel_type(string_class), build_with_kernel_type(string_class) or program(vector_class<program>, string_class).

Template Parameters

kernelT Typename specifying the name of the kernel to be built.

Parameters

buildOptions The string specifying the build options to provide to the underlying OpenCL API.

Definition at line 301 of file program.h.

◆ build_with_source() [1/2]

void cl::sycl::program::build_with_source	(	string_class	kernelSource,
		string_class	buildOptions = `""`
	)

inline

Creates and builds a program from OpenCL C kernel source and optional build options.

This function produces a ready-to-run program.

Parameters

kernelSource	Source of the OpenCL kernel.
buildOptions	The string specifying the build options to provide to the underlying OpenCL API.

Definition at line 324 of file program.h.

◆ build_with_source() [2/2]

void cl::sycl::program::build_with_source	(	const char *	kernelSrc,
		const char *	compileOptions
	)

Creates and builds a program from OpenCL C kernel source and optional build options.

This function produces a ready-to-run program.

Parameters

kernelSource	Source of the OpenCL kernel.
buildOptions	The string specifying the build options to provide to the underlying OpenCL API.

◆ compile_with_kernel_type()

template<typename kernelT >

void cl::sycl::program::compile_with_kernel_type ( string_class compileOptions = "" )

inline

Compile a SYCL kernel using name and optional custom compile options.

This function creates a ready-to-link program.

Note that calling this member function is invalid if the program has already been successfully compiled, built or linked via either link(string_class), compile_with_kernel_type(string_class), build_with_kernel_type(string_class) or program(vector_class<program>, string_class).

Template Parameters

kernelT Typename specifying the name of the kernel to be compiled.

Parameters

compileOptions String of compile options that will be passed to the OpenCL driver.

Definition at line 242 of file program.h.

◆ compile_with_source() [1/2]

void cl::sycl::program::compile_with_source	(	string_class	kernelSource,
		string_class	compileOptions = `""`
	)

inline

Compiles a program from the given OpenCL C kernel source.

Note that calling this member function is invalid if the program has already been successfully compiled, built or linked via either link(string_class), compile_with_kernel_type(string_class), build_with_kernel_type(string_class) or program(vector_class<program>, string_class).

Parameters

kernelSource	to compile
compilation	options for the source

Definition at line 268 of file program.h.

◆ compile_with_source() [2/2]

void cl::sycl::program::compile_with_source	(	const char *	kernelSrc,
		const char *	compileOptions
	)

Compiles a program from the given OpenCL C kernel source.

Note that calling this member function is invalid if the program has already been successfully compiled, built or linked via either link(string_class), compile_with_kernel_type(string_class), build_with_kernel_type(string_class) or program(vector_class<program>, string_class).

Parameters

kernelSource	to compile
compilation	options for the source

◆ create_from_built_in_kernel() [1/2]

void cl::sycl::program::create_from_built_in_kernel ( string_class kernel )

inline

Creates a valid cl_program from a pre-built kernel provided by the underlying OpenCL implementation.

Parameters

kernel The name of the built-in kernel

Definition at line 281 of file program.h.

◆ create_from_built_in_kernel() [2/2]

void cl::sycl::program::create_from_built_in_kernel ( const char * kernel )

Creates a valid cl_program from a pre-built kernel provided by the underlying OpenCL implementation.

Parameters

kernel The name of the built-in kernel

◆ get()

cl_program cl::sycl::program::get ( ) const

Inter-op member function that returns the underlying cl_program.

Returns: The underlying cl_program usable by the OpenCL API.

◆ get_binaries()

vector_class<vector_class<char> > cl::sycl::program::get_binaries ( ) const

Return the list of binaries that were used to compile and link the program.

Returns: The list of binaries that were used to compile and link the program.

◆ get_build_options()

string_class cl::sycl::program::get_build_options ( ) const

inline

Return the build options used when building the program.

Returns: A string specifying the options used when building the program.

Definition at line 461 of file program.h.

◆ get_compile_options()

string_class cl::sycl::program::get_compile_options ( ) const

inline

Return the compile options used when compiling the program.

Returns: A string specifying the compile options used when compiling the program.

Definition at line 445 of file program.h.

◆ get_context()

context cl::sycl::program::get_context ( ) const

Retrieves the context associated with the program.

Returns: Associated context.

◆ get_devices()

vector_class<cl::sycl::device> cl::sycl::program::get_devices ( ) const

Return the list of devices associated with the program.

Returns: The list of associated devices.

◆ get_info()

template<info::program param>

COMPUTECPP_EXPORT info::param_traits<info::program, param>::return_type cl::sycl::program::get_info ( ) const

Retrieves information about the program.

The runtime query the OpenCL API and then converts the result into the SYCL representation before returning it.

Template Parameters

param Information to retrieve.

Returns: The information in the SYCL format.

◆ get_kernel() [1/3]

template<typename kernelT >

kernel cl::sycl::program::get_kernel ( ) const

inline

Retrieve a SYCL kernel object described by the typename kernelT.

Template Parameters

kernelT Typename specifying the name of the kernel to be returned.

Returns: The kernel that has been created from the kernel name parameter.

Definition at line 387 of file program.h.

◆ get_kernel() [2/3]

kernel cl::sycl::program::get_kernel ( string_class kernelName ) const

inline

Retrieve a SYCL kernel object described by the kernel name.

Parameters

kernelName The string specifying the kernel name.

Returns: The kernel that has been created form the kernel name parameter.

Definition at line 402 of file program.h.

◆ get_kernel() [3/3]

kernel cl::sycl::program::get_kernel ( const char * kernelName ) const

◆ get_link_options()

string_class cl::sycl::program::get_link_options ( ) const

inline

Return the link options used when linking the program.

Returns: A string specifying the link options used when linking the program.

Definition at line 453 of file program.h.

◆ get_no_retain()

cl_program cl::sycl::program::get_no_retain ( ) const

protected

Inter-op member function that returns the underlying cl_program.

Returns: The underlying cl_program usable by the OpenCL API.

◆ get_state()

program_state cl::sycl::program::get_state ( ) const

Retrieves the current build state of the program.

Returns: The build state of the program

◆ has_kernel() [1/3]

template<typename kernelT >

bool cl::sycl::program::has_kernel ( ) const

inline

Checks whether the program contains a kernel specified by the type.

Template Parameters

kernelT Typename specifying the name of the kernel to be returned.

Returns: True if the SYCL kernel function defined by the type kernelT is an available kernel, either within the encapsulated cl_program (if this SYCL program is an OpenCL program), or on the host, otherwise false.

Definition at line 357 of file program.h.

◆ has_kernel() [2/3]

bool cl::sycl::program::has_kernel ( string_class kernelName ) const

inline

Checks whether the program contains a kernel specified by the name.

Returns: True if the OpenCL C kernel function defined by kernelName is an available kernel within the encapsulated cl_program and this SYCL program is not a host program, otherwise false.

Definition at line 373 of file program.h.

◆ has_kernel() [3/3]

bool cl::sycl::program::has_kernel ( const char * kernelName ) const

◆ is_host()

bool cl::sycl::program::is_host ( ) const

Returns whether the program was constructed from a host context.

Returns: True if program constructed from a host context

◆ is_linked()

bool cl::sycl::program::is_linked ( ) const

Return a bool specifying whether the program has been linked.

Returns: True if the program has been linked.

◆ link() [1/2]

void cl::sycl::program::link ( string_class linkOptions = "" )

inline

Link all compiled programs using the (optional) link options.

This function produce a ready-to-run program using a compiled program.

Note that calling this member function is invalid if the cl_program has already been successfully built or linked via either link(string_class), build_with_kernel_type(string_class) or program(vector_class<program>, string_class).

Parameters

linkOptions String specifying the link options to provide to the underlying OpenCL API.

Definition at line 343 of file program.h.

◆ link() [2/2]

void cl::sycl::program::link ( const char * linkOptions )

Link all compiled programs using the (optional) link options.

This function produce a ready-to-run program using a compiled program.

Note that calling this member function is invalid if the cl_program has already been successfully built or linked via either link(string_class), build_with_kernel_type(string_class) or program(vector_class<program>, string_class).

Parameters

linkOptions String specifying the link options to provide to the underlying OpenCL API.

◆ operator=() [1/2]

program& cl::sycl::program::operator= ( const program & rhs )

default

Assignment operator that initialises a copy of the program with the same underlying cl_program, associated context and list of associated devices.

Parameters

rhs	The program being assigned from.

◆ operator=() [2/2]

program& cl::sycl::program::operator= ( program && rhs )

default

Assignment operator that initialises a copy of the program with the same underlying cl_program, associated context and list of associated devices.

Parameters

rhs	The program being assigned from.

◆ select_kernel_binary_info()

template<typename BIType >

static const detail::kernel_binary_info& cl::sycl::program::select_kernel_binary_info	(	const detail::kernel_binary_info &	hostBinaryInfo,
		const BIType *	binList,
		size_t	binListSize,
		const context &	ctx
	)

inlinestaticprotected

Retrieves binary info to build a program.

Template Parameters

BIType

Parameters

hostBinaryInfo	Host binary info. Will be selected if the context is a host context
binList	The list available binaries for this program
binListSize	The length of `binList`
ctx	Context to retrieve binary info for

Returns: Reference to kernel binary info

Definition at line 688 of file program.h.

◆ select_kernel_binary_info_helper()

template<typename BIType >

static const BIType& cl::sycl::program::select_kernel_binary_info_helper	(	const BIType *	binList,
		size_t	binListSize,
		ddevice_wkptr	dev
	)

inlinestaticprotected

Retrieve an appropriate binary to build a program.

If a sycl stub file has more than one binary in it (e.g. spir64 and spirv64) the environment variable COMPUTECPP_TARGET_BITCODE can be used to select which binary this function will return. If the binary for the specified value is not found, the first one available will be returned.

Parameters

binList	The list available binaries for this program.
binListSize	The length of `binList`.
dev	Device where the binary will execute on.

Returns: A reference to the selected binary.

Definition at line 643 of file program.h.

Friends And Related Function Documentation

◆ operator!=

bool operator!=	(	const program &	lhs,
		const program &	rhs
	)

friend

Determines if lhs and rhs are not equal.

Parameters

lhs	Left-hand-side object in comparison
rhs	Right-hand-side object in comparison

Returns: True if different underlying objects

Definition at line 219 of file program.h.

◆ operator==

bool operator==	(	const program &	lhs,
		const program &	rhs
	)

friend

Determines if lhs and rhs are equal.

Parameters

lhs	Left-hand-side object in comparison
rhs	Right-hand-side object in comparison

Returns: True if same underlying object

Definition at line 210 of file program.h.

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

program.h

menu_bookReference

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ program() [1/8]

◆ program() [2/8]

◆ program() [3/8]

◆ program() [4/8]

◆ program() [5/8]

◆ program() [6/8]

◆ program() [7/8]

◆ program() [8/8]

◆ ~program()

Member Function Documentation

◆ build_with_kernel_type()

◆ build_with_source() [1/2]

◆ build_with_source() [2/2]

◆ compile_with_kernel_type()

◆ compile_with_source() [1/2]

◆ compile_with_source() [2/2]

◆ create_from_built_in_kernel() [1/2]

◆ create_from_built_in_kernel() [2/2]

◆ get()

◆ get_binaries()

◆ get_build_options()

◆ get_compile_options()

◆ get_context()

◆ get_devices()

◆ get_info()

◆ get_kernel() [1/3]

◆ get_kernel() [2/3]

◆ get_kernel() [3/3]

◆ get_link_options()

◆ get_no_retain()

◆ get_state()

◆ has_kernel() [1/3]

◆ has_kernel() [2/3]

◆ has_kernel() [3/3]

◆ is_host()

◆ is_linked()

◆ link() [1/2]

◆ link() [2/2]

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ select_kernel_binary_info()

◆ select_kernel_binary_info_helper()

Friends And Related Function Documentation

◆ operator!=

◆ operator==

Select a Product

oneAPI

Dark Mode

Light Mode

Codeplay.com

SYCL.tech

Codeplay Developer

Codeplay Open Source