Links a set of compiled program objects and libraries for all the devices or a specific device(s) in the OpenCL context and creates an executable.
cl_program
clLinkProgram
(
| cl_context context, |
cl_uint num_devices, | |
const cl_device_id *device_list, | |
const char *options, | |
cl_uint num_input_programs, | |
const cl_program *input_programs, | |
void (CL_CALLBACK *pfn_notify) (cl_program program, void *user_data), | |
void *user_data, | |
cl_int *errcode_ret) |
context
Must be a valid OpenCL context.
device_list
A pointer to a list of devices that are in context
.
If device_list
is a NULL value, the link is performed
for all devices associated with context
for which a
compiled object is available. If device_list
is a
non-NULL value, the compile is performed for devices specified in this
list for which a compiled object is available.
num_devices
The number of devices listed in device_list
.
options
A pointer to a null-terminated string of characters that describes the link options to be used for building the program executable. See clBuildProgram for a list of supported compiler and linker options.
num_input_programs
Specifies the number of programs in array referenced by input_programs
.
input_programs
An array of program objects that are compiled binaries or libraries
that are to be linked to create the program executable. For each device
in device_list
or if device_list
is NULL the list of devices associated with context
,
the following cases occur:
All programs specified by input_programs
contain a compiled binary or library for the device. In this case,
a link is performed to generate a program executable for this device.
None of the programs contain a compiled binary or library for that device. In this case, no link is performed and there will be no program executable generated for this device.
All other cases will return a
CL_INVALID_OPERATION
error.
pfn_notify
A function pointer to a notification routine. The notification routine is a callback function that an application can register and which will be called when the program executable has been built (successfully or unsuccessfully).
If pfn_notify
is not NULL,
clLinkProgram
does not need to wait for the linker
to complete and can return immediately once the linking operation can
begin. Once the linker has completed, the pfn_notify
callback function is called which returns the program object returned
by clLinkProgram
. The application can query the link
status and log for this program object. This callback function may be called
asynchronously by the OpenCL implementation. It is the application’s
responsibility to ensure that the callback function is thread-safe.
If pfn_notify
is NULL, clLinkProgram
does not return until the linker has completed.
user_data
Will be passed as an argument when pfn_notify
is called.
user_data
can be NULL.
clLinkProgram
creates a new program object which
contains this executable. The executable binary can be queried using
clGetProgramInfo(program
,
CL_PROGRAM_BINARIES
, ...) and can be specified to
clCreateProgramWithBinary
to create a new program object.
The devices associated with the returned program object will be the list of devices
specified by device_list
or if device_list
is NULL it will be the list of devices associated with context
.
The linking operation can begin if the context, list of devices, input programs and
linker options specified are all valid and appropriate host and device resources
needed to perform the link are available. If the linking operation can begin,
clLinkProgram
returns a valid non-zero program object.
If pfn_notify
is NULL, the errcode_ret
will
be set to CL_SUCCESS
if the link operation was successful and
CL_LINK_FAILURE
if there is a failure to link the compiled
binaries and/or libraries.
If pfn_notify
is not NULL, clLinkProgram
does not have to wait until the linker to complete and can return
CL_SUCCESS
in errcode_ret
if the linking
operation can begin. The pfn_notify
callback function will
return a CL_SUCCESS
or CL_LINK_FAILURE
if the linking operation was successful or not.
Otherwise clLinkProgram
returns a NULL program object with an
appropriate error in errcode_ret
. The application should query
the linker status of this program object to check if the link was successful or not.
The list of errors that can be returned are:
context
is not a valid context.
device_list
is NULL and num_devices
is greater than zero, or if
device_list
is not NULL and num_devices
is zero.
num_input_programs
is zero and input_programs
is NULL or if
num_input_programs
is zero and input_programs
is not NULL or if num_input_programs
is not zero and
input_programs
is NULL.
input_programs
are not valid program objects.
pfn_notify
is
NULL but user_data
is not NULL.
device_list
are not in the list of devices associated with
context
.
options
are invalid
device_list
by a previous call to
clCompileProgram
or clBuildProgram
for program
has not completed.
input_programs
argument above are not followed.
CL_DEVICE_LINKER_AVAILABLE
specified
in the table of allowed values for param_name
for
clGetDeviceInfo
is set to CL_FALSE
.