write_pipe

Read packet from pipe into ptr.

`int write_pipe (`	pipe gentype `p`,
	const gentype `*ptr)`

`int write_pipe (`	pipe gentype `p`,
	reserve_id_t `reserve_id`,
	uint `index`,
	const gentype `*ptr)`

Description

For the form without reserve_id, write packet specified by ptr into pipe p. Returns 0 if write_pipe is successful and a negative value if the pipe is full.

For the form using reserve_id, write packet specified by ptr to the reserved area of the pipe referred to by reserve_id and index. The reserved pipe entries are referred to by indices that go from 0 … num_packets – 1. Returns 0 if write_pipe is successful and a negative value otherwise.

We use the generic type name gentype to indicate the built-in OpenCL C scalar or vector integer or floating-point data types or any user defined type built from these scalar and vector data types can be used as the type for the arguments to the pipe functions listed in this section. The half scalar and vector types can only be used if the cl_khr_fp16 extension is supported. The double scalar and vector types can only be used if double precision is supported.

A pipe is identified by specifying the pipe keyword with a type. The data type specifies the size of each packet in the pipe. The pipe keyword is a type modifier. When it is applied to another type T, the result is a pipe type whose elements (or packets) are of type T. The packet type T may be any supported OpenCL C scalar and vector integer or floating-point data types, or a user-defined type built from these scalar and vector data types.

The read_only (or __read_only) and write_only (or __write_only) qualifiers can also be used with the pipe qualifier to identify if a pipe can be read from or written to by a kernel. The default qualifier is read_only.

A kernel cannot read from and write to the same pipe object. Using the read_write (or __read_write) qualifier with the pipe qualifier is a compilation error.

The macro CLK_NULL_RESERVE_ID refers to an invalid reservation ID.

NOTE: The read_pipe and write_pipe functions that take a reservation ID as an argument can be used to read from or write to a packet index. These built-ins can be used to read from or write to a packet index one or multiple times. If a packet index that is reserved for writing is not written to using the write_pipe function, the contents of that packet in the pipe are undefined. commit_read_pipe and work_group_commit_read_pipe remove the entries reserved for reading from the pipe. commit_write_pipe and work_group_commit_write_pipe ensures that the entries reserved for writing are all added in-order as one contiguous set of packets to the pipe.

There can only be CL_DEVICE_PIPE_MAX_ACTIVE_RESERVATIONS (refer to the list of possible values for parame_name for clGetDeviceInfo(table 4.3)) reservations active (i.e. reservation IDs that have been reserved but not committed) per work-item or work-group for a pipe in a kernel executing on a device.

Work-item based reservations made by a work-item are ordered in the pipe as they are ordered in the program. Reservations made by different work-items that belong to the same work-group can be ordered using the work-group barrier function. The order of work-item based reservations that belong to different work-groups is implementation defined.

Work-group based reservations made by a work-group are ordered in the pipe as they are ordered in the program. The order of work-group based reservations by different work-groups is implementation defined.

Restrictions

Pipes can only be passed as arguments to a function (including kernel functions). The C operators (refer to section 6.3 of the OpenCL 2.0 specification) cannot be used with variables declared with the pipe qualifier.

The pipe qualifier cannot be used with variables declared inside a kernel, a structure or union field, a pointer type, an array, global variables declared in program scope or the return type of a function.

The following behavior is undefined:

A kernel fails to call reserve_pipe before calling read_pipe or write_pipe that take a reservation ID.
A kernel calls read_pipe, write_pipe, commit_read_pipe or commit_write_pipe with an invalid reservation ID.
A kernel calls read_pipe or write_pipe with an valid reservation ID but with an index that is not a value from 0 ... num_packets - 1 specified to the corresponding call to reserve_pipe.
A kernel calls read_pipe or write_pipe with a reservation ID that has already been committed (i.e. a commit_read_pipe or commit_write_pipe with this reservation ID has already been called).
A kernel fails to call commit_read_pipe for any reservation ID obtained by a prior call to reserve_read_pipe.
A kernel fails to call commit_write_pipe for any reservation ID obtained by a prior call to reserve_write_pipe.
The contents of the reserved data packets in the pipe are undefined if the kernel does not call write_pipe for all entries that were reserved by the corresponding call to reserve_pipe.
Calls to read_pipe that takes a reservation ID and commit_read_pipe or write_pipe that takes a reservation ID and commit_write_pipe for a given reservation ID must be called by the same kernel that made the reservation using reserve_read_pipe or reserve_write_pipe. The reservation ID cannot be passed to another kernel including child kernels.

Example

In the following example

kernel void foo (read_only pipe fooA_t pipeA, write_only pipe fooB_t pipeB) { ... }

pipeA is a read-only pipe object, and pipeB is a write-only pipe object.

Specification

OpenCL Specification

Also see

Pipe Functions

Copyright © 2007-2013 The Khronos Group Inc. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and/or associated documentation files (the "Materials"), to deal in the Materials without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Materials, and to permit persons to whom the Materials are furnished to do so, subject to the condition that this copyright notice and permission notice shall be included in all copies or substantial portions of the Materials.