cl_command_queue clCreateCommandQueueWithProperties(
| cl_context context, |
cl_device_id device, | |
const cl_queue_properties *properties, | |
cl_int *errcode_ret) |
context
Must be a valid OpenCL context.
device
Must be a device associated with context
.
It can either be in the list of devices specified when
context
is created using
clCreateContext
or have the same device type as the device type specified
when the context
is created using
clCreateContextFromType.
properties
Specifies a list of properties for the
command-queue and their corresponding values.
Each property name is immediately followed
by the corresponding desired value. The list is
terminated with 0. The list of supported properties
is described in the table below. If a
supported property and its value is not specified in
properties
, its default value will be used.
properties
can be NULL in which case
the default values for supported command-queue properties
will be used.
Queue Properties | Property Value | Description |
---|---|---|
CL_QUEUE_PROPERTIES
|
cl_command_queue_- properties | This is a bitfield and can be set to a combination of the following values:
If |
CL_QUEUE_SIZE
|
cl_uint | Specifies the size of the device queue in bytes. This can only be specified if
For best performance, this should be ≤
If |
errcode_ret
Returns an appropriate error code. If errcode_ret
is NULL
, no error code is returned.
OpenCL objects such as memory, program and kernel objects are created using a context. Operations on these objects are performed using a command-queue. The command-queue can be used to queue a set of operations (referred to as commands) in order. Having multiple command-queues allows applications to queue multiple independent commands without requiring synchronization. Note that this should work as long as these objects are not being shared. Sharing of objects across multiple command-queues will require the application to perform appropriate synchronization. This is described in Appendix A of the specification.
The OpenCL functions that are submitted to a command-queue are enqueued in the order
the calls are made but can be configured to execute in-order or out-of-order. The
properties
argument in clCreateCommandQueueWithProperties
can be used to specify the execution order.
If the CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE
property of a command-queue is not set, the commands enqueued to a
command-queue execute in order. For example, if an application calls
clEnqueueNDRangeKernel
to execute kernel A followed by a
clEnqueueNDRangeKernel
to execute kernel B, the application can assume that kernel A finishes first and then
kernel B is executed. If the memory objects output by kernel A are inputs to kernel
B then kernel B will see the correct data in memory objects produced by execution of
kernel A. If the CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE
property
of a command-queue is set, then there is no guarantee that kernel A will finish before
kernel B starts execution.
Applications can configure the commands enqueued to a command-queue to execute
out-of-order by setting the CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE
property of the command-queue. This can be specified when the command-queue is
created. In out-of-order execution mode there is no guarantee that the enqueued
commands will finish execution in the order they were queued. As there is no
guarantee that kernels will be executed in order, i.e. based on when the
clEnqueueNDRangeKernel
calls are made within a command-queue, it is therefore possible that an earlier
clEnqueueNDRangeKernel
call to execute kernel A identified by event A may execute and/or finish later than a
clEnqueueNDRangeKernel
call to execute kernel B which was called by the application at a later
point in time. To guarantee a specific order of execution of kernels, a
wait on a particular event (in this case event A) can be used. The wait for
event A can be specified in the event_wait_list
argument to
clEnqueueNDRangeKernel
for kernel B.
In addition, a wait for events (clEnqueueMarkerWithWaitList) or a barrier (clEnqueueBarrierWithWaitList) command can be enqueued to the command-queue. The wait for events command ensures that previously enqueued commands identified by the list of events to wait for have finished before the next batch of commands is executed. The barrier command ensures that all previously enqueued commands in a command-queue have finished execution before the next batch of commands is executed.
Similarly, commands to read, write, copy or map memory objects that are enqueued after
clEnqueueNDRangeKernel or
clEnqueueNativeKernel
commands are not guaranteed to wait for kernels scheduled for execution to have
completed (if the CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE
property is set). To ensure correct ordering of commands, the event object returned by
clEnqueueNDRangeKernel or
clEnqueueNativeKernel
can be used to enqueue a wait for event or a barrier command can be enqueued that
must complete before reads or writes to the memory object(s) occur.
clCreateCommandQueueWithProperties
returns a valid non-zero command-queue and
errcode_ret
is set to CL_SUCCESS if the
command-queue is created successfully. Otherwise, it returns a NULL value with one
of the following error values returned in errcode_ret
:
context
is not a valid
context.
device
is not a valid
device or is not associated with context
.
properties
are not valid.
properties
are valid but are not supported by the device.
clGetCommandQueueInfo, clReleaseCommandQueue, clRetainCommandQueue, clCreateContext, clCreateContextFromType, clEnqueueNDRangeKernel