C Specification

To enqueue a command to wait on a set of semaphores, call the function

// Provided by cl_khr_semaphore
cl_int clEnqueueWaitSemaphoresKHR(
    cl_command_queue command_queue,
    cl_uint num_sema_objects,
    const cl_semaphore_khr* sema_objects,
    const cl_semaphore_payload_khr* sema_payload_list,
    cl_uint num_events_in_wait_list,
    const cl_event* event_wait_list,
    cl_event* event);
clEnqueueWaitSemaphoresKHR is provided by the cl_khr_semaphore extension.

Parameters

  • command_queue specifies a valid command-queue.

  • num_sema_objects specifies the number of semaphore objects to wait on.

  • sema_objects points to the list of semaphore objects to wait on. The length of the list must be at least num_sema_objects.

  • sema_payload_list points to the list of values of type cl_semaphore_payload_khr containing valid semaphore payload values to wait on. This can be set to NULL or will be ignored if no semaphores in the list of sema_objects require a payload.

  • num_events_in_wait_list specifies the number of events in event_wait_list.

  • event_wait_list specifies list of events that need to complete before clEnqueueWaitSemaphoresKHR can be executed. If event_wait_list is NULL, then clEnqueueWaitSemaphoresKHR 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 that associated with command_queue must be the same.

  • event returns an event object that identifies this particular command and can be used to query 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 query the status of this command or queue a wait for this command to complete.

Description

The semaphore wait command waits for a list of events to complete and a list of semaphore objects to become signaled. The semaphore wait command returns an event which can be waited on to ensure that all events in the event_wait_list have completed and all semaphores in sema_objects have been signaled. clEnqueueWaitSemaphoresKHR will not return until the binary semaphores in sema_objects are in a state that makes them safe to re-signal. If necessary, implementations may block in clEnqueueWaitSemaphoresKHR to ensure the correct state of semaphores when returning. There are no implications from this behavior for the state of event or the events in event_wait_list when clEnqueueWaitSemaphoresKHR returns. Waiting on the same binary semaphore twice without an interleaving signal may lead to undefined behavior.

When command_queue is an out-of-order command-queue there are no implicit dependencies between the semaphore wait command and commands enqueued into the command-queue after the semaphore wait command. If such dependencies are required, applications may enqueue a command-queue barrier after the semaphore wait command, to explicitly add dependencies between the semaphore wait command and subsequent commands.

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

  • CL_INVALID_COMMAND_QUEUE

    • if command_queue is not a valid command-queue, or

    • if the device associated with command_queue is not same as one of the devices specified by CL_SEMAPHORE_DEVICE_HANDLE_LIST_KHR at the time of creating one or more of sema_objects, or

    • if one or more of sema_objects belong to a context that does not contain a device associated with command_queue.

  • CL_INVALID_VALUE if num_sema_objects is 0.

  • CL_INVALID_SEMAPHORE_KHR if any of the semaphore objects specified by sema_objects is not valid.

  • CL_INVALID_CONTEXT if the context associated with command_queue and any of the semaphore objects in sema_objects are not the same, or if the context associated with command_queue and that associated with events in event_wait_list are not the same.

  • CL_INVALID_VALUE if any of the semaphore objects specified by sema_objects requires a semaphore payload and sema_payload_list is NULL.

  • CL_INVALID_EVENT_WAIT_LIST

    • if event_wait_list is NULL and num_events_in_wait_list is not 0, or

    • if 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_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST if the execution status of any of the events in event_wait_list is a negative integer value.

  • 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_queue, cl_event, cl_khr_semaphore, cl_semaphore_khr, cl_semaphore_payload_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