system facilities
     such as <function>select</function>, <function>poll</function>,
     <function>WaitForMultipleObjectEx</function>, etc.
    </para>

    <para>
     The client application should generally maintain a queue of work
     remaining to be dispatched and a queue of work that has been dispatched
     but not yet had its results processed. When the socket is writable
     it should dispatch more work. When the socket is readable it should
     read results and process them, matching them up to the next entry in
     its corresponding results queue.  Based on available memory, results from the
     socket should be read frequently: there's no need to wait until the
     pipeline end to read the results.  Pipelines should be scoped to logical
     units of work, usually (but not necessarily) one transaction per pipeline.
     There's no need to exit pipeline mode and re-enter it between pipelines,
     or to wait for one pipeline to finish before sending the next.
    </para>

    <para>
     An example using <function>select()</function> and a simple state
     machine to track sent and received work is in
     <filename>src/test/modules/libpq_pipeline/libpq_pipeline.c</filename>
     in the PostgreSQL source distribution.
    </para>
   </sect3>
  </sect2>

  <sect2 id="libpq-pipeline-functions">
   <title>Functions Associated with Pipeline Mode</title>

   <variablelist>

    <varlistentry id="libpq-PQpipelineStatus">
     <term><function>PQpipelineStatus</function><indexterm><primary>PQpipelineStatus</primary></indexterm></term>

     <listitem>
      <para>
      Returns the current pipeline mode status of the
      <application>libpq</application> connection.
<synopsis>
PGpipelineStatus PQpipelineStatus(const PGconn *conn);
</synopsis>
      </para>

      <para>
       <function>PQpipelineStatus</function> can return one of the following values:

       <variablelist>
        <varlistentry>
         <term>
          <literal>PQ_PIPELINE_ON</literal>
         </term>
         <listitem>
          <para>
           The <application>libpq</application> connection is in
           pipeline mode.
          </para>
         </listitem>
        </varlistentry>

        <varlistentry>
         <term>
          <literal>PQ_PIPELINE_OFF</literal>
         </term>
         <listitem>
          <para>
           The <application>libpq</application> connection is
           <emphasis>not</emphasis> in pipeline mode.
          </para>
         </listitem>
        </varlistentry>

        <varlistentry>
         <term>
          <literal>PQ_PIPELINE_ABORTED</literal>
         </term>
         <listitem>
          <para>
           The <application>libpq</application> connection is in pipeline
           mode and an error occurred while processing the current pipeline.
           The aborted flag is cleared when <function>PQgetResult</function>
           returns a result of type <literal>PGRES_PIPELINE_SYNC</literal>.
          </para>
         </listitem>
        </varlistentry>

       </variablelist>
      </para>
     </listitem>
    </varlistentry>

    <varlistentry id="libpq-PQenterPipelineMode">
     <term><function>PQenterPipelineMode</function><indexterm><primary>PQenterPipelineMode</primary></indexterm></term>

     <listitem>
      <para>
      Causes a connection to enter pipeline mode if it is currently idle or
      already in pipeline mode.

<synopsis>
int PQenterPipelineMode(PGconn *conn);
</synopsis>

      </para>
      <para>
       Returns 1 for success.
       Returns 0 and has no effect if the connection is not currently
       idle, i.e., it has a result ready, or it is waiting for more
       input from the server, etc.
       This function does not actually send anything to the server,
       it just changes the <application>libpq</application> connection
       state.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry id="libpq-PQexitPipelineMode">
     <term><function>PQexitPipelineMode</function><indexterm><primary>PQexitPipelineMode</primary></indexterm></term>