OpenCL™规范 5.13.2. 创建信号量

5.13.2. Creating Semaphores

5.13.2. 创建信号量

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. cclCreateSemaphoreWithPropertiesKHR 由cl_khr_semaphore扩展提供。

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

• context标识创建的cl_semaphore_khr将属于的有效OpenCL上下文。

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

• ​sema_props在以0结尾的<property_name，property_value>对的列表中指定了其他信号量属性。CL_SEMAPHORE_TYPE_KHR必须是sema_prop指定的属性列表的一部分。

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

cl_semaphore_properties_khr将以下新属性添加到可能支持的属性列表中，这些属性可以传递给clCreateSemaphoreWithPropertiesKHR：

Table 52. List of supported semaphore creation properties by clCreateSemaphoreWithPropertiesKHR

表52 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. ​指定要与信号量关联的OpenCL设备列表（以CL_SEMAPHORE_DEVICE_HANDLE_LIST_END_KHR结尾）。列表中只允许有一个设备。
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. ​指定可用于导出正在创建的信号量的信号量句柄类型属性列表（以CL_SEMAPHORE_EXPORT_HANDLE_TYPES_LIST_END_KHR结尾）。

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

​如果CL_SEMAPHORE_DEVICE_HANDLE_LIST_KHR未指定为sema_props的一部分，则默认情况下，clCreateSemaphoreWithPropertiesKHR 创建的信号量对象可供context中的所有设备访问。对于多设备上下文，必须在sema_props中指定CL_SEMAPHORE_DEVICE_HANDLE_LIST_KHR。

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

errcode_ret返回适当的错误代码。如果errcode_ret为NULL，则不返回错误代码。

clCreateSemaphoreWithPropertiesKHR returns a valid semaphore object in an un-signaled state and 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:

​clCreateSemaphoreWithPropertiesKHR 返回一个处于未信号状态的有效信号量对象，如果函数执行成功，errcode_ret设置为CL_SUCCESS。否则，它将返回一个NULL值，并在errcode_ret中返回以下错误值之一：

• CL_INVALID_CONTEXT if context is not a valid context.

• 如果context 不是有效的上下文，则返回CL_INVALID_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_PROPERTY，如果sema_props中的属性名不是支持的属性名，如果为支持的属性名称指定的值无效，或者如果多次指定相同的属性名称。此外，如果上下文是多设备上下文，且sema_props未指定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_DEVICE，如果CL_SEMAPHORE_DEVICE_HANDLE_LIST_KHR被指定为sema_props的一部分，但它并不能准确标识一个有效设备；或者，如果CL_SEMAPHORE_HANDLE_LIST_KHR标识的设备不是context中的设备之一。

• CL_INVALID_VALUE

  • if sema_props is NULL, or

  • 如果sema_props为NULL，或

  • 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

  • ​如果sema_props没有为成功创建cl_semaphore_khr所需的最小属性集（即CL_SEMAPHORE_TYPE_KHR）指定<property，value>对，或

• CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.

• CL_OUT_OF_RESOURCES，如果无法在设备上分配OpenCL实现所需的资源。

• CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.

• CL_OUT_OF_HOST_MEMORY，如果无法在主机上分配OpenCL实现所需的资源。

• 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_DEVICE，如果由属性CL_SEMAPHORE_DEVICE_HANDLE_LIST_KHR标识的一个或多个设备无法导入请求的外部信号量句柄类型。

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

• 如果在CL_SEMAPHORE_EXPORT_HANDLE_TYPES_KHR列表中指定了多个信号量句柄类型，则为CL_INVALID_VALUE。

• 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_OPERATION如果props_list指定了一个cl_external_semaphore_handle_type_khr ，后面跟着一个句柄以及CL_SEMAPHORE_EXPORT_HANDLE_TYPES_KHR。不允许从通过导入外部信号量句柄创建的信号量导出信号量句柄。