C Specification

To create a host or device command-queue on a specific device, call the function

// Provided by CL_VERSION_2_0
cl_command_queue clCreateCommandQueueWithProperties(
    cl_context context,
    cl_device_id device,
    const cl_queue_properties* properties,
    cl_int* errcode_ret);
clCreateCommandQueueWithProperties is missing before version 2.0.

or the equivalent

// Provided by cl_khr_create_command_queue
cl_command_queue clCreateCommandQueueWithPropertiesKHR(
    cl_context context,
    cl_device_id device,
    const cl_queue_properties_khr* properties,
    cl_int* errcode_ret);
clCreateCommandQueueWithPropertiesKHR is provided by the cl_khr_create_command_queue extension.

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 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 will return an appropriate error code. If errcode_ret is NULL, no error code is returned.

Description

Table 1. List of supported queue creation properties by clCreateCommandQueueWithProperties
Queue Property 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:

CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE - Determines whether the commands queued in the command-queue are executed in-order or out-of-order. If set, the commands in the command-queue are executed out-of-order. Otherwise, commands are executed in-order.

CL_QUEUE_PROFILING_ENABLE - Enable or disable profiling of commands in the command-queue. If set, the profiling of commands is enabled. Otherwise profiling of commands is disabled.

CL_QUEUE_ON_DEVICE - Indicates that this is a device queue. If CL_QUEUE_ON_DEVICE is set, CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE [1] must also be set.

missing before version 2.0.

CL_QUEUE_ON_DEVICE_DEFAULT [2] - indicates that this is the default device queue. This can only be used with CL_QUEUE_ON_DEVICE.

missing before version 2.0.

If CL_QUEUE_PROPERTIES is not specified an in-order host command-queue is created for the specified device

CL_QUEUE_SIZE

missing before version 2.0.

cl_uint

Specifies the size of the device queue in bytes.

This can only be specified if CL_QUEUE_ON_DEVICE is set in CL_QUEUE_PROPERTIES. This must be a value ≤ CL_DEVICE_QUEUE_ON_DEVICE_MAX_SIZE.

For best performance, this should be ≤ CL_DEVICE_QUEUE_ON_DEVICE_PREFERRED_SIZE.

If CL_QUEUE_SIZE is not specified, the device queue is created with CL_DEVICE_QUEUE_ON_DEVICE_PREFERRED_SIZE as the size of the queue.

CL_QUEUE_PRIORITY_KHR

provided by the cl_khr_priority_hints extension.

cl_queue_priority_khr

Specifies a priority hint for command queues belonging to the same OpenCL context.

NOTE: Refer to the user guide associated with each implementation supporting this extension for its priority behavior guarantees, if any.

CL_QUEUE_PRIORITY_HIGH_KHR - Indicates command queues should have high priority.

CL_QUEUE_PRIORITY_MED_KHR - Indicates command queues should have medium priority.

CL_QUEUE_PRIORITY_LOW_KHR - Indicates command queues should have low priority.

If CL_QUEUE_PRIORITY_KHR is not specified, the default priority CL_QUEUE_PRIORITY_MED_KHR is used.

CL_QUEUE_THROTTLE_KHR

provided by the cl_khr_throttle_hints extension.

cl_queue_throttle_khr

Specifies a throttle hint for a command queue.

NOTE: Refer to the user guide associated with each implementation supporting this extension for its throttling behavior guarantees, if any.

CL_QUEUE_THROTTLE_HIGH_KHR - Indicates the queue should execute at full throttle, which may consume more energy.

CL_QUEUE_THROTTLE_MED_KHR - Indicates normal throttling behavior.

CL_QUEUE_THROTTLE_LOW_KHR - Indicates the queue should execute at low throttle, optimized for lowest energy consumption.

If CL_QUEUE_THROTTLE_KHR is not specified, the default priority CL_QUEUE_THROTTLE_MED_KHR is used.

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_INVALID_QUEUE_PROPERTIES if the cl_khr_priority_hints extension is supported, the CL_QUEUE_PRIORITY_KHR property is specified, and the queue is a CL_QUEUE_ON_DEVICE.

  • CL_INVALID_QUEUE_PROPERTIES if the cl_khr_throttle_hints extension is supported, the CL_QUEUE_THROTTLE_KHR property is specified, and the queue is a CL_QUEUE_ON_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.

See Also

CL_VERSION_2_0, cl_context, cl_device_id, cl_int, cl_khr_create_command_queue, cl_queue_properties, cl_queue_properties_khr

Document Notes

For more information, see the OpenCL Specification

This page is extracted from the OpenCL Specification. Fixes and changes should be made to the Specification, not directly.

Copyright

Copyright 2014-2025 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0

1. Only out-of-order device queues are supported.
2. The application must create a default device queue if any kernels containing calls to get_default_queue are enqueued. There can only be one default device queue for each device within a context. If a default device queue has already been created, calling clCreateCommandQueueWithProperties with CL_QUEUE_PROPERTIES set to CL_QUEUE_ON_DEVICE and CL_QUEUE_ON_DEVICE_DEFAULT will return the default device queue that has already been created and increment its reference count by 1.