get_pipe_num_packets

Description

Returns the number of available entries in the pipe.
The number of available entries in a pipe is a
dynamic value. The value returned should be
considered immediately stale.

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.