C Specification

To record a barrier operation used as a synchronization point, call the function

// Provided by cl_khr_command_buffer
cl_int clCommandBarrierWithWaitListKHR(
    cl_command_buffer_khr command_buffer,
    cl_command_queue command_queue,
    const cl_command_properties_khr* properties,
    cl_uint num_sync_points_in_wait_list,
    const cl_sync_point_khr* sync_point_wait_list,
    cl_sync_point_khr* sync_point,
    cl_mutable_command_khr* mutable_handle);
clCommandBarrierWithWaitListKHR is provided by the cl_khr_command_buffer extension.

Parameters

  • command_buffer refers to a valid command-buffer object.

  • command_queue specifies the command-queue the command will be recorded to.
    If the cl_khr_command_buffer_multi_device extension is not supported, only a single command-queue is supported, and command_queue must be NULL.
    If the cl_khr_command_buffer_multi_device extension is supported and command_queue is NULL, then only one command-queue must have been set on command_buffer creation; otherwise, command_queue must not be NULL.

  • properties specifies a list of properties for the command and their corresponding values. Each property name is immediately followed by the corresponding desired value. The list is terminated with 0. The cl_khr_command_buffer extension does not define any properties, but supported properties may be defined by layered extensions in future.

  • sync_point_wait_list, num_sync_points_in_wait_list specify synchronization-points that need to complete before this particular command can be executed.

    If sync_point_wait_list is NULL, num_sync_points_in_wait_list must be 0. If sync_point_wait_list is not NULL, the list of synchronization-points pointed to by sync_point_wait_list must be valid and num_sync_points_in_wait_list must be greater than 0. The synchronization-points specified in sync_point_wait_list are device-side synchronization-points. The command-buffer associated with synchronization-points in sync_point_wait_list must be the same as command_buffer. The memory associated with sync_point_wait_list can be reused or freed after the function returns.

    If sync_point_wait_list is NULL, then this particular command waits until all previous recorded commands to command_queue have completed.

  • sync_point returns a synchronization-point ID that identifies this particular command. Synchronization-point objects are unique and can be used to identify this barrier command later on. sync_point can be NULL in which case it will not be possible for the application to record a wait for this command to complete. If the sync_point_wait_list and the sync_point arguments are not NULL, the sync_point argument should not refer to an element of the sync_point_wait_list array.

  • mutable_handle returns a handle to the command. This parameter is unused, and must be NULL.

Description

clCommandBarrierWithWaitListKHR waits for either a list of synchronization-points to complete, or if the list is empty it waits for all commands previously recorded in command_buffer to complete before it completes. This command blocks command execution, that is, any following commands recorded after it do not execute until it completes.

clCommandBarrierWithWaitListKHR returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:

  • CL_INVALID_COMMAND_QUEUE if the cl_khr_command_buffer_multi_device extension is not supported and command_queue is not NULL.

  • CL_INVALID_COMMAND_QUEUE if the cl_khr_command_buffer_multi_device extension is supported; and either command_queue is NULL and command_buffer was created with more than one queue, or command_queue is not NULL and not a command-queue listed on command_buffer creation.

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

  • CL_INVALID_CONTEXT if command_queue is not NULL, and the context associated with command_queue and command_buffer is not the same.

  • CL_INVALID_OPERATION if command_buffer has been finalized.

  • CL_INVALID_VALUE if values specified in properties are not valid.

  • CL_INVALID_VALUE if mutable_handle is not NULL.

  • CL_INVALID_SYNC_POINT_WAIT_LIST_KHR if sync_point_wait_list is NULL and num_sync_points_in_wait_list is > 0, or sync_point_wait_list is not NULL and num_sync_points_in_wait_list is 0, or if synchronization-point objects in sync_point_wait_list are not valid synchronization-points.

  • 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_properties_khr, cl_command_queue, cl_khr_command_buffer, cl_mutable_command_khr, cl_sync_point_khr, 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