C Specification

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

// Provided by cl_khr_semaphore
cl_int clEnqueueSignalSemaphoresKHR(
    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);
clEnqueueSignalSemaphoresKHR 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 signal.

  • sema_objects points to the list of semaphore objects to signal. 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 semaphore payload values to signal. 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 points to the list of events that need to complete before clEnqueueSignalSemaphoresKHR can be executed. If event_wait_list is NULL, then clEnqueueSignalSemaphoresKHR 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 signal command waits for a list of events to complete and then signals a list of semaphore objects. The semaphore signal 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. The successful completion of the event generated by clEnqueueSignalSemaphoresKHR called on one or more semaphore objects of type CL_SEMAPHORE_TYPE_BINARY_KHR changes the state of the corresponding semaphore objects to signaled. clEnqueueSignalSemaphoresKHR will not return until the binary semaphores in sema_objects are in a state that makes them safe to wait on again. If necessary, implementations may block in clEnqueueSignalSemaphoresKHR 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 clEnqueueSignalSemaphoresKHR returns. Signaling the same binary semaphore twice without an interleaving wait may lead to undefined behavior.

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

clEnqueueSignalSemaphoresKHR 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