C Specification

To enqueue a command-buffer to execute on command-queues, call the function

// Provided by cl_khr_command_buffer
cl_int clEnqueueCommandBufferKHR(
    cl_uint num_queues,
    cl_command_queue* queues,
    cl_command_buffer_khr command_buffer,
    cl_uint num_events_in_wait_list,
    const cl_event* event_wait_list,
    cl_event* event);
clEnqueueCommandBufferKHR is provided by the cl_khr_command_buffer extension.

Parameters

  • num_queues is the number of command-queues listed in queues.

  • queues is a pointer to an ordered list of command-queues to execute the command-buffer on. queues can be NULL, in which case the default command-queues used on command-buffer creation are used and num_queues must be 0.

  • command_buffer refers to a valid command-buffer object.

  • event_wait_list, num_events_in_wait_list specify events that need to complete before this particular command can be executed. If event_wait_list is NULL, then this particular command does not wait on any event to complete. If event_wait_list is NULL, num_events_in_wait_list must be 0. If event_wait_list is not NULL, the list of events pointed to by event_wait_list must be valid and num_events_in_wait_list must be greater than 0. The events specified in event_wait_list act as synchronization points. The context associated with events in event_wait_list and command_queue must be the same. The memory associated with event_wait_list can be reused or freed after the function returns.

  • event will return an event object that identifies this command and can be used to query for profiling information or queue a wait for this particular command to complete. event can be NULL in which case it will not be possible for the application to wait on this command or query it for profiling information.

Description

To enqueue a command-buffer it must be in a Executable state, see clFinalizeCommandBufferKHR.

clEnqueueCommandBufferKHR returns CL_SUCCESS if the command-buffer execution was successfully queued, or one of the errors below:

  • CL_INVALID_COMMAND_BUFFER_KHR if command_buffer is not a valid command-buffer.

  • CL_INVALID_OPERATION if command_buffer has not been finalized.

  • CL_INVALID_OPERATION if command_buffer was not created with the CL_COMMAND_BUFFER_SIMULTANEOUS_USE_KHR flag and is in the Pending state.

  • CL_INVALID_VALUE if queues is NULL and num_queues is > 0, or queues is not NULL and num_queues is 0.

  • CL_INVALID_VALUE if num_queues is > 0 and not the same value as num_queues set on command_buffer creation.

  • CL_INVALID_COMMAND_QUEUE if any element of queues is not a valid command-queue.

  • CL_INCOMPATIBLE_COMMAND_QUEUE_KHR if the properties of any command-queue in queues contains a property not specified by CL_DEVICE_COMMAND_BUFFER_SUPPORTED_QUEUE_PROPERTIES_KHR.

  • CL_INCOMPATIBLE_COMMAND_QUEUE_KHR if the properties of any command-queue in queues does not contain the minimum properties specified by CL_DEVICE_COMMAND_BUFFER_REQUIRED_QUEUE_PROPERTIES_KHR.

  • CL_INVALID_DEVICE if any element of queues does not have the same device as the command-queue set on command_buffer creation at the same list index.

  • CL_INVALID_CONTEXT if any element of queues does not have the same context as the command-queue set on command_buffer creation at the same list index.

  • CL_INVALID_CONTEXT if context associated with command_buffer and events in event_wait_list are not the same.

  • CL_OUT_OF_RESOURCES if there is a failure to queue the execution instance of command_buffer on the command-queues because of insufficient resources needed to execute command_buffer.

  • CL_INVALID_EVENT_WAIT_LIST if event_wait_list is NULL and num_events_in_wait_list > 0, or event_wait_list is not NULL and num_events_in_wait_list is 0, or if event objects in event_wait_list are not valid events.

  • 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_command_buffer_khr, cl_command_queue, cl_event, cl_khr_command_buffer, cl_uint

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