C Specification

To create a semaphore object, call the function

// Provided by cl_khr_semaphore
cl_semaphore_khr clCreateSemaphoreWithPropertiesKHR(
    cl_context context,
    const cl_semaphore_properties_khr* sema_props,
    cl_int* errcode_ret);
clCreateSemaphoreWithPropertiesKHR is provided by the cl_khr_semaphore extension.

Parameters

  • context identifies a valid OpenCL context that the created cl_semaphore_khr will belong to.

  • sema_props specifies additional semaphore properties in the form list of <property_name, property_value> pairs terminated with 0. CL_SEMAPHORE_TYPE_KHR must be part of the list of properties specified by sema_props.

Description

Following new properties are added to the list of possible supported properties by cl_semaphore_properties_khr that can be passed to clCreateSemaphoreWithPropertiesKHR:

Table 1. List of supported semaphore creation properties by clCreateSemaphoreWithPropertiesKHR
Semaphore Property Property Value Description

CL_SEMAPHORE_TYPE_KHR

cl_semaphore_type_khr

Specifies the type of semaphore to create. This property is always required.

CL_SEMAPHORE_DEVICE_HANDLE_LIST_KHR

cl_device_id[]

Specifies the list of OpenCL devices (terminated with CL_SEMAPHORE_DEVICE_HANDLE_LIST_END_KHR) to associate with the semaphore. Only a single device is permitted in the list.

CL_SEMAPHORE_EXPORT_HANDLE_TYPES_KHR

provided by the cl_khr_external_semaphore extension.

cl_external_semaphore_handle_type_khr[]

Specifies the list of semaphore handle type properties (terminated with CL_SEMAPHORE_EXPORT_HANDLE_TYPES_LIST_END_KHR) that can be used to export the semaphore being created.

If CL_SEMAPHORE_DEVICE_HANDLE_LIST_KHR is not specified as part of sema_props, the semaphore object created by clCreateSemaphoreWithPropertiesKHR is by default associated with all devices in the context. For a multi-device context CL_SEMAPHORE_DEVICE_HANDLE_LIST_KHR must be specified in sema_props.

The properties used to create a semaphore from an external semaphore handle are described for the corresponding extensions.

errcode_ret returns an appropriate error code. If errcode_ret is NULL, no error code is returned.

clCreateSemaphoreWithPropertiesKHR returns a valid semaphore object in an un-signaled state and errcode_ret is set to CL_SUCCESS if the function is executed successfully. Otherwise, it returns a NULL value with one of the following error values returned in errcode_ret:

  • CL_INVALID_CONTEXT if context is not a valid context.

  • CL_INVALID_PROPERTY if a property name in sema_props is not a supported property name, if the value specified for a supported property name is not valid, or if the same property name is specified more than once. Additionally, if context is a multiple device context and sema_props does not specify CL_SEMAPHORE_DEVICE_HANDLE_LIST_KHR.

  • CL_INVALID_DEVICE if CL_SEMAPHORE_DEVICE_HANDLE_LIST_KHR is specified as part of sema_props, but it does not identify exactly one valid device; or if a device identified by CL_SEMAPHORE_DEVICE_HANDLE_LIST_KHR is not one of the devices within context.

  • CL_INVALID_VALUE

    • if sema_props is NULL, or

    • if sema_props do not specify <property, value> pairs for minimum set of properties (i.e. CL_SEMAPHORE_TYPE_KHR) required for successful creation of a cl_semaphore_khr, or

  • 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.

  • CL_INVALID_DEVICE if one or more devices identified by properties CL_SEMAPHORE_DEVICE_HANDLE_LIST_KHR cannot import the requested external semaphore handle type.

  • CL_INVALID_VALUE if more than one semaphore handle type is specified in the CL_SEMAPHORE_EXPORT_HANDLE_TYPES_KHR list.

  • CL_INVALID_OPERATION If props_list specifies a cl_external_semaphore_handle_type_khr followed by a handle as well as CL_SEMAPHORE_EXPORT_HANDLE_TYPES_KHR. Exporting a semaphore handle from a semaphore that was created by importing an external semaphore handle is not permitted.

  • CL_INVALID_PROPERTY if sema_props includes more than one external semaphore handle.

See Also

cl_context, cl_int, cl_khr_semaphore, cl_semaphore_properties_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