<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "xhtml1-transitional.dtd">
<!-- saved from url=(0013)about:internet -->
<?xml-stylesheet type="text/xsl" href="mathml.xsl"?><html xmlns="http://www.w3.org/1999/xhtml" xmlns:pref="http://www.w3.org/2002/Math/preference" xmlns:xlink="http://www.w3.org/1999/xlink" pref:renderer="mathplayer-dl">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <style xmlns="" type="text/css">
    /* This style sets a margin around the entire page */
        html, body {
            margin: 10px;
        }

        p {
            font: normal 16px verdana, sans-serif;
            margin: 0;
            padding-bottom:12px;
        }

        h1 {
            font: bold 25px verdana, sans-serif;
            margin-top: 0;
            margin-bottom: 3px;
            padding-top: 0;
            padding-bottom: 0;
        }

        h2 {
            font: bold 19px verdana, sans-serif;
            margin-top: 28px;
            margin-bottom: 3px;
            padding-top: 0;
            padding-bottom: 0;
        }

        h3 {
            font: bold 19px verdana, sans-serif !important;
            margin-top: 28px;
            margin-bottom: 3px;
            padding-top: 0;
            padding-bottom: 0;
        }

        li {
            font: normal 16px verdana, sans-serif;
            margin-top: 0;
            margin-bottom: 18px;
            padding-top: 0;
            padding-bottom: 0;
        }

        .pdparam {
            font: italic 16px verdana, sans-serif;
        }

                .term {
                        font: italic 16px verdana, sans-serif;
                        font-weight: normal;
                }

                .type {
                        font: normal 16px verdana, sans-serif !important;
                }

                .parameter {
                        font-style: italic;
                        }

        a:link, a:visited {
            color: blue;
            text-decoration: none;
            font: normal 16px;
        }

        a:hover {
            background-color: #FFFF99;
            font: normal 16px;
        }

        div.funcsynopsis {
            text-align: left;
            background-color: #e6e6e6;
            font: normal 16px verdana, sans-serif;
                        padding-top: 10px;
                        padding-bottom: 10px;
        }

        div.funcsynopsis table {
            border-collapse: separate;
            font: normal 16px verdana, sans-serif;
        }

        div.funcsynopsis td {
            background-color: #e6e6e6;
            border: 0 solid #000;
            padding: 1px;
            font: normal 16px verdana, sans-serif;
        }

        div.refsect1 {
            font-family: verdana, sans-serif;
            font-size: 16px;
        }

        code.constant {
            font: normal 16px courier new, monospace !important;
        }

                span.errorname {
            font: normal 16px verdana, sans-serif !important;
        }

        code.function {
            font: bold 16px verdana, sans-serif !important;
        }

        b.fsfunc {
            font: bold 16px verdana, sans-serif !important;
        }

        code.varname {
            font: italic 16px verdana, sans-serif;
        }

        code.replaceable {
            font: italic 16px courier new, monospace;
        }

        code.funcdef {
            font: normal 16px verdana, sans-serif !important;
        }

        .citerefentry {
            font: normal 16px verdana, sans-serif !important;
        }

        .parameter {
            font-style: italic;
        }

        code.fsfunc {
            font: normal 16px verdana, sans-serif !important;
        }

        /* PARAMETER: This style controls spacing between the terms in Parameter section */
        dt {
            margin-top: 15px;
        }

        /* TABLES: These styles apply to all tables OTHER than the Synopsis and Example tables */
        div.refsect1 table {
            width: 100%;
                        margin-top: 10px;
            background-color: #FFF;
                        border-collapse: collapse;
                        border-color: #000;
            border-width: 1px;
                        font: normal 16px verdana, sans-serif;
        }

        div.refsect1 th {
                        border-collapse: collapse;
                        border-color: #000;
            border-width: 1px;
            font: bold 16px verdana, sans-serif;
        }

        div.refsect1 td {
            background-color: #FFF;
            padding: 5px;
            vertical-align: text-top;
                        border-collapse: collapse;
                        border-color: #000;
            border-width: 1px;
            font: normal 16px verdana, sans-serif;
        }

                  div.refsect1 p{
            font: normal 16px verdana, sans-serif;
            margin-top: 8px;
            margin-bottom: 8px;
            padding-top: 0;
            padding-bottom: 0;
        }


        /* EXAMPLE: These styles apply only to the Example section */
        div.refsect2 {
            font: normal 16px courier new, monospace !important;
        }

        div.refsect2 table {
            margin-top: 0;
            background-color: #e6e6e6;
            width: 100%;
            border: 0 solid #000;
            padding: 2px;
            font: normal 16px courier new, monospace !important;
        }

        div.refsect2 td {
            background-color: #e6e6e6;
            font: normal 16px courier new, monospace !important;
                        white-space:pre;
        }

        /* COPYRIGHT: This style formats the text of the copyright statement at the bottom of the page */
        div.refsect3 {
            font: normal 11px verdana, sans-serif;
            margin-top: 50px;
            margin-bottom: 20px;
            padding-top: 0;
            padding-bottom: 0;
        }

</style>
    <title>read_pipe</title>
    <meta name="generator" content="DocBook XSL Stylesheets V1.79.1" />
    <meta name="keywords" content="read_pipe" />
  </head>
  <body>
    <div class="refentry">
      <a id="id-1"></a>
      <div class="titlepage"></div>
      <div xmlns="" class="refnamediv">
        <a xmlns="http://www.w3.org/1999/xhtml" id="read_pipe"></a>
        <h1>read_pipe</h1>
        <p>
            Read packet from <code xmlns="http://www.w3.org/1999/xhtml" class="varname">pipe</code> into <code xmlns="http://www.w3.org/1999/xhtml" class="varname">ptr</code>.
        </p>
      </div>
      <div class="refsynopsisdiv">
        <h2></h2>
        <div class="funcsynopsis">
          <table xmlns="" border="0" summary="Function synopsis" cellspacing="0" cellpadding="0">
            <tr valign="bottom">
              <td>
                <code xmlns="http://www.w3.org/1999/xhtml" class="funcdef">
                    <a class="link" href="scalarDataTypes.html" target="pagedisplay">int</a>
                    <strong class="fsfunc">
                        read_pipe
                    </strong>
                (</code>
                <td>read_only pipe gentype  <var xmlns="http://www.w3.org/1999/xhtml" class="pdparam">p</var>, </td>
              </td>
            </tr>
            <tr valign="top">
              <td> </td>
              <td>gentype  <var xmlns="http://www.w3.org/1999/xhtml" class="pdparam">*ptr</var><code>)</code></td>
            </tr>
          </table>
        </div>
        <div class="funcsynopsis">
          <table xmlns="" border="0" summary="Function synopsis" cellspacing="0" cellpadding="0">
            <tr valign="bottom">
              <td>
                <code xmlns="http://www.w3.org/1999/xhtml" class="funcdef">
                    <a class="link" href="scalarDataTypes.html" target="pagedisplay">int</a>
                    <strong class="fsfunc">
                        read_pipe
                    </strong>
                (</code>
                <td>read_only pipe gentype  <var xmlns="http://www.w3.org/1999/xhtml" class="pdparam">p</var>, </td>
              </td>
            </tr>
            <tr valign="top">
              <td> </td>
              <td><a xmlns="http://www.w3.org/1999/xhtml" class="link" href="enums.html#reserve_id_t" target="pagedisplay">reserve_id_t</a> <var xmlns="http://www.w3.org/1999/xhtml" class="pdparam">reserve_id</var>, </td>
            </tr>
            <tr valign="top">
              <td> </td>
              <td><a xmlns="http://www.w3.org/1999/xhtml" class="link" href="scalarDataTypes.html" target="pagedisplay">uint</a> <var xmlns="http://www.w3.org/1999/xhtml" class="pdparam">index</var>, </td>
            </tr>
            <tr valign="top">
              <td> </td>
              <td>gentype  <var xmlns="http://www.w3.org/1999/xhtml" class="pdparam">*ptr</var><code>)</code></td>
            </tr>
          </table>
        </div>
      </div>
      <div class="refsect1">
        <a id="description"></a>
        <h2>Description</h2>
        <p>
            For the form without <code class="varname">reserve_id</code>, 
            read packet from pipe <code class="varname">p</code> into <code class="varname">ptr</code>. Returns 0 if 
            <code class="function">read_pipe</code> is successful and a negative value if the 
            pipe is empty.
        </p>
        <p>
            For the form using <code class="varname">reserve_id</code>, 
            read packet from the reserved area of the pipe 
            referred to by <code class="varname">reserve_id</code> and 
            <code class="varname">index</code> into <code class="varname">ptr</code>.
            The reserved pipe entries are referred to by indices 
            that go from 0 ... <code class="varname">num_packets</code> – 1.
            Returns 0 if <code class="function">read_pipe</code> is successful and a negative 
            value otherwise.
        </p>
        <p>
    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 
    <a class="citerefentry" href="cl_khr_fp16.html"><span class="citerefentry"><span class="refentrytitle">cl_khr_fp16</span></span></a> 
    extension is supported. The <span class="type">double</span> scalar 
    and vector types can only be used if double precision is supported.
</p>
        <h4><a id="id-1.5.5"></a>General information about pipes</h4>
        <p>
    A pipe is identified by specifying the <code class="code">pipe</code> 
    keyword with a type. The data type specifies the 
    size of each packet in the pipe. The <code class="code">pipe</code> 
    keyword is a type modifier. When it is applied to 
    another type <code class="code">T</code>, the result is a pipe type 
    whose elements (or packets) are of type <code class="code">T</code>. The packet 
    type <code class="code">T</code> 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.
</p>
        <p>
    The 
    <a class="citerefentry" href="qualifiers.html"><span class="citerefentry"><span class="refentrytitle">read_only</span></span></a> 
    (or <code class="code">__read_only</code>) and 
    <a class="citerefentry" href="qualifiers.html"><span class="citerefentry"><span class="refentrytitle">write_only</span></span></a>
    (or <code class="code">__write_only</code>) qualifiers
    must be used with the pipe qualifier when a pipe 
    is a parameter of a kernel or of a user-defined
    function to identify if a pipe can be read from 
    or written to by a kernel and its callees and
    enqueued child kernels. If no qualifier is specified, 
    <a class="citerefentry" href="qualifiers.html"><span class="citerefentry"><span class="refentrytitle">read_only</span></span></a> 
    is assumed.
</p>
        <p>
    A kernel cannot read from and write to the same pipe object. Using the 
    <a class="citerefentry" href="qualifiers.html"><span class="citerefentry"><span class="refentrytitle">read_write </span></span></a>
    (or <code class="code">__read_write</code>) qualifier with the pipe qualifier is a compilation error.
</p>
        <p>
    The macro <code class="constant">CLK_NULL_RESERVE_ID</code> refers to an invalid reservation ID.
</p>
        <p>
    NOTE: The 
    <a class="citerefentry" href="read_pipe.html"><span class="citerefentry"><span class="refentrytitle">read_pipe</span></span></a> and 
    <a class="citerefentry" href="write_pipe.html"><span class="citerefentry"><span class="refentrytitle">write_pipe</span></span></a> 
    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 
    <a class="citerefentry" href="write_pipe.html"><span class="citerefentry"><span class="refentrytitle">write_pipe</span></span></a> 
    function, the contents of that packet in the pipe are undefined. 
    <a class="citerefentry" href="commit_read_pipe.html"><span class="citerefentry"><span class="refentrytitle">commit_read_pipe</span></span></a> and 
    <a class="citerefentry" href="work_group_commit_read_pipe.html"><span class="citerefentry"><span class="refentrytitle">work_group_commit_read_pipe</span></span></a>
    remove the entries reserved for reading from the pipe. 
    <a class="citerefentry" href="commit_write_pipe.html"><span class="citerefentry"><span class="refentrytitle">commit_write_pipe</span></span></a> and 
    <a class="citerefentry" href="work_group_commit_write_pipe.html"><span class="citerefentry"><span class="refentrytitle">work_group_commit_write_pipe</span></span></a> 
    ensures that the entries reserved for writing are all added in-order 
    as one contiguous set of packets to the pipe.
</p>
        <p>
    There can only be <code class="constant">CL_DEVICE_PIPE_MAX_ACTIVE_RESERVATIONS</code> 
    (refer to the list of possible values for <code class="varname">parame_name</code>
    for <a class="citerefentry" href="clGetDeviceInfo.html"><span class="citerefentry"><span class="refentrytitle">clGetDeviceInfo</span></span></a>(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.
</p>
        <p>
    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.
</p>
        <p>
    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.
</p>
        <h4><a id="id-1.5.14"></a>Restrictions</h4>
        <p>
    Pipes can only be passed as arguments to a function 
    (including kernel functions). The C 
    <a class="citerefentry" href="operators.html"><span class="citerefentry"><span class="refentrytitle">operators</span></span></a> 
    (refer to section 6.3 of the OpenCL 2.0 specification) cannot be used with 
    variables declared with the <code class="code">pipe</code> qualifier.
</p>
        <p>
    The <code class="code">pipe</code> 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.
</p>
        <p>
    The following behavior is undefined:
</p>
        <p>
    </p>
        <div class="itemizedlist">
          <ul class="itemizedlist" style="list-style-type: disc; ">
            <li class="listitem">
            A kernel fails to call 
            <code class="function">reserve_pipe</code>
            before calling 
            <a class="citerefentry" href="read_pipe.html"><span class="citerefentry"><span class="refentrytitle">read_pipe</span></span></a> or 
            <a class="citerefentry" href="write_pipe.html"><span class="citerefentry"><span class="refentrytitle">write_pipe</span></span></a> that take a 
            reservation ID.
        </li>
            <li class="listitem">
            A kernel calls 
            <a class="citerefentry" href="read_pipe.html"><span class="citerefentry"><span class="refentrytitle">read_pipe</span></span></a>, 
            <a class="citerefentry" href="write_pipe.html"><span class="citerefentry"><span class="refentrytitle">write_pipe</span></span></a>, 
            <a class="citerefentry" href="commit_read_pipe.html"><span class="citerefentry"><span class="refentrytitle">commit_read_pipe</span></span></a> or 
            <a class="citerefentry" href="commit_write_pipe.html"><span class="citerefentry"><span class="refentrytitle">commit_write_pipe</span></span></a> with 
            an invalid reservation ID.
        </li>
            <li class="listitem">
            A kernel calls 
            <a class="citerefentry" href="read_pipe.html"><span class="citerefentry"><span class="refentrytitle">read_pipe</span></span></a> or 
            <a class="citerefentry" href="write_pipe.html"><span class="citerefentry"><span class="refentrytitle">write_pipe</span></span></a> 
            with an valid reservation ID but with an <code class="varname">index</code>
            that is not a value from 0 ... <code class="varname">num_packets</code> - 1 
            specified to the corresponding call to 
            <code class="function">reserve_pipe</code>.
        </li>
            <li class="listitem">
            A kernel calls 
            <a class="citerefentry" href="read_pipe.html"><span class="citerefentry"><span class="refentrytitle">read_pipe</span></span></a> or 
            <a class="citerefentry" href="write_pipe.html"><span class="citerefentry"><span class="refentrytitle">write_pipe</span></span></a> 
            with a reservation ID that has already been committed (i.e. a 
            <a class="citerefentry" href="commit_read_pipe.html"><span class="citerefentry"><span class="refentrytitle">commit_read_pipe</span></span></a> or 
            <a class="citerefentry" href="commit_write_pipe.html"><span class="citerefentry"><span class="refentrytitle">commit_write_pipe</span></span></a>
            with this reservation ID has 
            already been called).
        </li>
            <li class="listitem">
            A kernel fails to call 
            <a class="citerefentry" href="commit_read_pipe.html"><span class="citerefentry"><span class="refentrytitle">commit_read_pipe</span></span></a> 
            for any reservation ID obtained by a prior call 
            to <a class="citerefentry" href="reserve_read_pipe.html"><span class="citerefentry"><span class="refentrytitle">reserve_read_pipe</span></span></a>.
        </li>
            <li class="listitem">
            A kernel fails to call 
            <a class="citerefentry" href="commit_write_pipe.html"><span class="citerefentry"><span class="refentrytitle">commit_write_pipe</span></span></a> 
            for any reservation ID obtained by a prior call 
            to <a class="citerefentry" href="reserve_write_pipe.html"><span class="citerefentry"><span class="refentrytitle">reserve_write_pipe</span></span></a>.
        </li>
            <li class="listitem">
            The contents of the reserved data packets in the pipe are undefined if the kernel does not 
            call <a class="citerefentry" href="write_pipe.html"><span class="citerefentry"><span class="refentrytitle">write_pipe</span></span></a> 
            for all entries that were reserved by the corresponding call to 
            <code class="function">reserve_pipe</code>.
        </li>
            <li class="listitem">
            Calls to 
            <a class="citerefentry" href="read_pipe.html"><span class="citerefentry"><span class="refentrytitle">read_pipe</span></span></a> 
            that takes a reservation ID and 
            <a class="citerefentry" href="commit_read_pipe.html"><span class="citerefentry"><span class="refentrytitle">commit_read_pipe</span></span></a> or 
            <a class="citerefentry" href="write_pipe.html"><span class="citerefentry"><span class="refentrytitle">write_pipe</span></span></a> that 
            takes a reservation ID and 
            <a class="citerefentry" href="commit_write_pipe.html"><span class="citerefentry"><span class="refentrytitle">commit_write_pipe</span></span></a> 
            for a given reservation ID must be called 
            by the same kernel that made the reservation using 
            <a class="citerefentry" href="reserve_read_pipe.html"><span class="citerefentry"><span class="refentrytitle">reserve_read_pipe</span></span></a> or 
            <a class="citerefentry" href="reserve_write_pipe.html"><span class="citerefentry"><span class="refentrytitle">reserve_write_pipe</span></span></a>. 
            The reservation ID cannot be passed to another kernel including 
            child kernels.
        </li>
          </ul>
        </div>
        <p>
</p>
        <div class="refsect2">
          <a id="example1"></a>
          <h3>
            Example
        </h3>
          <p>
In the following example
        </p>
          <div class="informaltable">
            <table class="informaltable" border="0">
              <colgroup>
                <col align="left" class="col1" />
              </colgroup>
              <tbody>
                <tr>
                  <td align="left">
kernel void
foo (read_only pipe fooA_t pipeA, 
     write_only pipe fooB_t pipeB)
{
...
}
                        </td>
                </tr>
              </tbody>
            </table>
          </div>
          <p>
            <code class="code">pipeA</code> is a read-only pipe object, 
            and <code class="code">pipeB</code> is a write-only pipe object.
        </p>
        </div>
      </div>
      <div class="refsect1">
        <a id="specification"></a>
        <h2>Specification</h2>
        <p>
            <img src="pdficon_small1.gif" />

            <a href="https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#namedest=read_pipe" target="OpenCL Spec">OpenCL Specification</a>
        </p>
      </div>
      <div class="refsect1">
        <a id="seealso"></a>
        <h2>Also see</h2>
        <p>
            <a class="citerefentry" href="pipeFunctions.html"><span class="citerefentry"><span class="refentrytitle">Pipe Functions</span></span></a>
        </p>
      </div>
      <div xmlns="" class="refsect3" lang="en" xml:lang="en"><a xmlns="http://www.w3.org/1999/xhtml" id="Copyright"></a><h4 xmlns="http://www.w3.org/1999/xhtml"></h4><img xmlns="http://www.w3.org/1999/xhtml" src="KhronosLogo.jpg" /><p xmlns="http://www.w3.org/1999/xhtml"></p>Copyright © 2007-2015 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.
</div>
    </div>
  </body>
</html>