Skip to content

Files

Latest commit

 

History

History
98 lines (60 loc) · 3.9 KB

clCreateCommandQueueWithProperties.adoc

File metadata and controls

98 lines (60 loc) · 3.9 KB

clCreateCommandQueueWithProperties

Create a host or device command-queue on a specific device.

cl_command_queue clCreateCommandQueueWithProperties(cl_context context,
                                                    cl_device_id device,
                                                    const cl_queue_properties *properties,
                                                    cl_int *errcode_ret)

Parameters

context

Must be a valid OpenCL context.

device

Must be a device or sub-device associated with context. It can either be in the list of devices and sub-devices specified when context is created using clCreateContext or be a root device with the same device type as 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.

errcode_ret

Returns an appropriate error code. If errcode_ret is NULL, no error code is returned.

Notes

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.

Errors

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:

  • CL_INVALID_CONTEXT if context is not a valid context.

  • CL_INVALID_DEVICE if device is not a valid device or is not associated with context.

  • CL_INVALID_VALUE if values specified in properties are not valid.

  • CL_INVALID_QUEUE_PROPERTIES if values specified in properties are valid but are not supported by the device.

  • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.

  • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.

  • CL_INVALID_QUEUE_PROPERTIES if extension cl_khr_priority_hints is enabled and the CL_QUEUE_PRIORITY_KHR property is specified and the queue is a CL_QUEUE_ON_DEVICE.

  • CL_INVALID_QUEUE_PROPERTIES if extension cl_khr_throttle_hints is enabled and the CL_QUEUE_PRIORITY_KHR property is specified and the queue is a CL_QUEUE_ON_DEVICE.