OpenCL™规范 5.4.1. 创建管道对象

5.4.1. Creating Pipe Objects

5.4.1. 创建管道对象

To create a pipe object, call the function

若要创建管道对象，请调用函数

// Provided by CL_VERSION_2_0
cl_mem clCreatePipe(
    cl_context context,
    cl_mem_flags flags,
    cl_uint pipe_packet_size,
    cl_uint pipe_max_packets,
    const cl_pipe_properties* properties,
    cl_int* errcode_ret);

clCreatePipe is missing before version 2.0. 版本2.0之前缺少clCreatePipe。

• context is a valid OpenCL context used to create the pipe object.

• context是用于创建管道对象的有效OpenCL上下文。

• flags is a bit-field that is used to specify allocation and usage information such as the memory arena that should be used to allocate the pipe object and how it will be used. The Memory Flags table describes the possible values for flags. Only CL_MEM_READ_WRITE and CL_MEM_HOST_NO_ACCESS can be specified when creating a pipe object. If the value specified for flags is 0, the default is used which is CL_MEM_READ_WRITE | CL_MEM_HOST_NO_ACCESS.

• ​flags是一个位字段，用于指定分配和使用信息，例如应该用于分配管道对象的内存区域以及如何使用它。Memory Flags表描述了标志的可能值。创建管道对象时，只能指定CL_MEM_READ_WRITE和CL_MEM_HOST_NO_ACCESS。如果为标志指定的值为0，则使用默认值CL_MEM_READ_WRITE|CL_MEM_HOST_NO_ACCESS。

• pipe_packet_size is the size in bytes of a pipe packet.

• pipe_packet_size是管道数据包的大小（以字节为单位）。

• pipe_max_packets specifies the pipe capacity by specifying the maximum number of packets the pipe can hold.

• pipe_max_packets通过指定管道可以容纳的最大数据包数来指定管道容量。

• properties specifies a list of properties for the pipe and their corresponding values. Each property name is immediately followed by the corresponding desired value. The list is terminated with 0. Currently, in all OpenCL versions, properties must be NULL.

• properties指定管道的属性及其相应值的列表。每个属性名称后面紧跟着相应的所需值。列表以0终止。目前，在所有OpenCL版本中，属性都必须为NULL。

• errcode_ret will return an appropriate error code. If errcode_ret is NULL, no error code is returned.

• errcode_ret将返回相应的错误代码。如果errcode_ret为NULL，则不会返回任何错误代码。

clCreatePipe returns a valid non-zero pipe object and errcode_ret is set to CL_SUCCESS if the pipe object is created successfully. Otherwise, it returns a NULL value with one of the following error values returned in errcode_ret:

clCreatePipe返回一个有效的非零管道对象，如果管道对象创建成功，则errcode_ret设置为CL_SUCCESS。否则，它将返回一个NULL值，并在errcode_ret中返回以下错误值之一：

• CL_INVALID_CONTEXT if context is not a valid context.

• CL_INVALID_CONTEXT（如果context不是有效上下文）。

• CL_INVALID_OPERATION if no devices in context support pipes.

• CL_INVALID_OPERATION（如果context中没有设备支持管道）。

• CL_INVALID_VALUE if values specified in flags are not as defined above.

• CL_INVALID_VALUE，如果flags中指定的值与上述定义不同。

• CL_INVALID_VALUE if properties is not NULL.

• CL_INVALID_VALUE（如果properties不为NULL）。

• CL_INVALID_PIPE_SIZE if pipe_packet_size is 0 or the pipe_packet_size exceeds CL_DEVICE_PIPE_MAX_PACKET_SIZE value specified in the Device Queries table for all devices in context or if pipe_max_packets is 0.

• CL_INVALID_PIPE_SIZE如果pipe_packet_size为0，或者pipe_packet_size超过context中所有设备的“设备查询”表中指定的CL_DEVICE_PIPE_MAX_PACKET_SIZE值，或者如果pipe_max_packets为0。

• CL_MEM_OBJECT_ALLOCATION_FAILURE if there is a failure to allocate memory for the pipe object.

• CL_MEM_OBJECT_ALLOCATION_FAILURE（如果为管道对象分配内存失败）。

• 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实现所需的资源失败。

Pipes follow the same memory consistency model as defined for buffer and image objects. The pipe state i.e. contents of the pipe across kernel-instances (on the same or different devices) is enforced at a synchronization point.