C Specification

To query information about a semaphore object, call the function

// Provided by cl_khr_semaphore
cl_int clGetSemaphoreInfoKHR(
    cl_semaphore_khr sema_object,
    cl_semaphore_info_khr param_name,
    size_t param_value_size,
    void* param_value,
    size_t* param_value_size_ret);
clGetSemaphoreInfoKHR is provided by the cl_khr_semaphore extension.

Parameters

  • sema_object specifies the semaphore object being queried.

  • param_name is a constant that specifies the semaphore information to query, and must be one of the values shown in the Semaphore Queries table.

  • param_value is a pointer to memory where the result of the query is returned as described in the Semaphore Queries table. If param_value is NULL, it is ignored.

  • param_value_size specifies the size in bytes of memory pointed to by param_value. This size must be greater than or equal to the size of the return type specified in the Semaphore Queries table. If param_value is NULL, it is ignored.

  • param_value_size_ret returns the actual size in bytes of data being queried by param_value. If param_value_size_ret is NULL, it is ignored.

Description

Table 1. List of parameter names supported by clGetSemaphoreInfoKHR
Semaphore Info Return Type Description

CL_SEMAPHORE_CONTEXT_KHR

cl_context

Returns the context specified when the semaphore is created.

CL_SEMAPHORE_REFERENCE_COUNT_KHR [1]

cl_uint

Returns the semaphore reference count.

CL_SEMAPHORE_PROPERTIES_KHR

cl_semaphore_properties_khr[]

Return the properties argument specified in clCreateSemaphoreWithPropertiesKHR.

The implementation must return the values specified in the properties argument in the same order and without including additional properties.

CL_SEMAPHORE_TYPE_KHR

cl_semaphore_type_khr

Returns the semaphore type.

CL_SEMAPHORE_PAYLOAD_KHR

cl_semaphore_payload_khr

Returns the semaphore payload value. For semaphores of type CL_SEMAPHORE_TYPE_BINARY_KHR the payload value returned will be 0 if the semaphore is in an un-signaled state, and 1 if it is in a signaled state.

CL_SEMAPHORE_DEVICE_HANDLE_LIST_KHR

cl_device_id[]

Returns the list of OpenCL devices the semaphore is associated with.

CL_SEMAPHORE_EXPORT_HANDLE_TYPES_KHR

cl_external_semaphore_handle_type_khr[]

Returns the list of external semaphore handle types that may be used for exporting. The size of this query may be 0 indicating that this semaphore does not support any handle types for exporting.

CL_SEMAPHORE_EXPORTABLE_KHR

cl_bool[]

Returns CL_TRUE if the semaphore is exportable and CL_FALSE otherwise.

clGetSemaphoreInfoKHR returns CL_SUCCESS if the information is queried successfully. Otherwise, it returns one of the following errors:

  • CL_INVALID_SEMAPHORE_KHR if sema_object is not a valid semaphore.

  • CL_INVALID_VALUE if param_name is not one of the supported values, or if the size in bytes specified by param_value_size is less than size of the return type specified in the Semaphore Queries table and param_value is not NULL.

  • 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_khr_semaphore, cl_semaphore_info_khr, cl_semaphore_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. The reference count returned should be considered immediately stale. It is unsuitable for general use in applications. This feature is provided for identifying memory leaks.