begriffs open source - ai-pg/blob - full-docs/src/sgml/html/libpq-async.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>32.4. Asynchronous Command Processing</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="libpq-exec.html" title="32.3. Command Execution Functions" /><link rel="next" href="libpq-pipeline-mode.html" title="32.5. Pipeline Mode" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">32.4. Asynchronous Command Processing</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="libpq-exec.html" title="32.3. Command Execution Functions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="libpq.html" title="Chapter 32. libpq — C Library">Up</a></td><th width="60%" align="center">Chapter 32. <span class="application">libpq</span> — C Library</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="libpq-pipeline-mode.html" title="32.5. Pipeline Mode">Next</a></td></tr></table><hr /></div><div class="sect1" id="LIBPQ-ASYNC"><div class="titlepage"><div><div><h2 class="title" style="clear: both">32.4. Asynchronous Command Processing <a href="#LIBPQ-ASYNC" class="id_link">#</a></h2></div></div></div><a id="id-1.7.3.11.2" class="indexterm"></a><p>
   3    The <a class="xref" href="libpq-exec.html#LIBPQ-PQEXEC"><code class="function">PQexec</code></a> function is adequate for submitting
   4    commands in normal, synchronous applications.  It has a few
   5    deficiencies, however, that can be of importance to some users:
   6
   7    </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
   8       <a class="xref" href="libpq-exec.html#LIBPQ-PQEXEC"><code class="function">PQexec</code></a> waits for the command to be completed.
   9       The application might have other work to do (such as maintaining a
  10       user interface), in which case it won't want to block waiting for
  11       the response.
  12      </p></li><li class="listitem"><p>
  13       Since the execution of the client application is suspended while it
  14       waits for the result, it is hard for the application to decide that
  15       it would like to try to cancel the ongoing command.  (It can be done
  16       from a signal handler, but not otherwise.)
  17      </p></li><li class="listitem"><p>
  18       <a class="xref" href="libpq-exec.html#LIBPQ-PQEXEC"><code class="function">PQexec</code></a> can return only one
  19       <code class="structname">PGresult</code> structure.  If the submitted command
  20       string contains multiple <acronym class="acronym">SQL</acronym> commands, all but
  21       the last <code class="structname">PGresult</code> are discarded by
  22       <a class="xref" href="libpq-exec.html#LIBPQ-PQEXEC"><code class="function">PQexec</code></a>.
  23      </p></li><li class="listitem"><p>
  24       <a class="xref" href="libpq-exec.html#LIBPQ-PQEXEC"><code class="function">PQexec</code></a> always collects the command's entire result,
  25       buffering it in a single <code class="structname">PGresult</code>.  While
  26       this simplifies error-handling logic for the application, it can be
  27       impractical for results containing many rows.
  28      </p></li></ul></div><p>
  29   </p><p>
  30    Applications that do not like these limitations can instead use the
  31    underlying functions that <a class="xref" href="libpq-exec.html#LIBPQ-PQEXEC"><code class="function">PQexec</code></a> is built from:
  32    <a class="xref" href="libpq-async.html#LIBPQ-PQSENDQUERY"><code class="function">PQsendQuery</code></a> and <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a>.
  33    There are also
  34    <a class="xref" href="libpq-async.html#LIBPQ-PQSENDQUERYPARAMS"><code class="function">PQsendQueryParams</code></a>,
  35    <a class="xref" href="libpq-async.html#LIBPQ-PQSENDPREPARE"><code class="function">PQsendPrepare</code></a>,
  36    <a class="xref" href="libpq-async.html#LIBPQ-PQSENDQUERYPREPARED"><code class="function">PQsendQueryPrepared</code></a>,
  37    <a class="xref" href="libpq-async.html#LIBPQ-PQSENDDESCRIBEPREPARED"><code class="function">PQsendDescribePrepared</code></a>,
  38    <a class="xref" href="libpq-async.html#LIBPQ-PQSENDDESCRIBEPORTAL"><code class="function">PQsendDescribePortal</code></a>,
  39    <a class="xref" href="libpq-async.html#LIBPQ-PQSENDCLOSEPREPARED"><code class="function">PQsendClosePrepared</code></a>, and
  40    <a class="xref" href="libpq-async.html#LIBPQ-PQSENDCLOSEPORTAL"><code class="function">PQsendClosePortal</code></a>,
  41    which can be used with <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> to duplicate
  42    the functionality of
  43    <a class="xref" href="libpq-exec.html#LIBPQ-PQEXECPARAMS"><code class="function">PQexecParams</code></a>,
  44    <a class="xref" href="libpq-exec.html#LIBPQ-PQPREPARE"><code class="function">PQprepare</code></a>,
  45    <a class="xref" href="libpq-exec.html#LIBPQ-PQEXECPREPARED"><code class="function">PQexecPrepared</code></a>,
  46    <a class="xref" href="libpq-exec.html#LIBPQ-PQDESCRIBEPREPARED"><code class="function">PQdescribePrepared</code></a>,
  47    <a class="xref" href="libpq-exec.html#LIBPQ-PQDESCRIBEPORTAL"><code class="function">PQdescribePortal</code></a>,
  48    <a class="xref" href="libpq-exec.html#LIBPQ-PQCLOSEPREPARED"><code class="function">PQclosePrepared</code></a>, and
  49    <a class="xref" href="libpq-exec.html#LIBPQ-PQCLOSEPORTAL"><code class="function">PQclosePortal</code></a>
  50    respectively.
  51
  52    </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQSENDQUERY"><span class="term"><code class="function">PQsendQuery</code><a id="id-1.7.3.11.4.19.1.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQSENDQUERY" class="id_link">#</a></dt><dd><p>
  53        Submits a command to the server without waiting for the result(s).
  54        1 is returned if the command was successfully dispatched and 0 if
  55        not (in which case, use <a class="xref" href="libpq-status.html#LIBPQ-PQERRORMESSAGE">
  56       <code class="function">PQerrorMessage</code>
  57
  58      </a> to get more
  59        information about the failure).
  60 </p><pre class="synopsis">
  61 int PQsendQuery(PGconn *conn, const char *command);
  62 </pre><p>
  63
  64        After successfully calling <a class="xref" href="libpq-async.html#LIBPQ-PQSENDQUERY"><code class="function">PQsendQuery</code></a>, call
  65        <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> one or more times to obtain the
  66        results.  <a class="xref" href="libpq-async.html#LIBPQ-PQSENDQUERY"><code class="function">PQsendQuery</code></a> cannot be called again
  67        (on the same connection) until <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a>
  68        has returned a null pointer, indicating that the command is done.
  69       </p><p>
  70        In pipeline mode, this function is disallowed.
  71       </p></dd><dt id="LIBPQ-PQSENDQUERYPARAMS"><span class="term"><code class="function">PQsendQueryParams</code><a id="id-1.7.3.11.4.19.2.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQSENDQUERYPARAMS" class="id_link">#</a></dt><dd><p>
  72        Submits a command and separate parameters to the server without
  73        waiting for the result(s).
  74 </p><pre class="synopsis">
  75 int PQsendQueryParams(PGconn *conn,
  76                       const char *command,
  77                       int nParams,
  78                       const Oid *paramTypes,
  79                       const char * const *paramValues,
  80                       const int *paramLengths,
  81                       const int *paramFormats,
  82                       int resultFormat);
  83 </pre><p>
  84
  85        This is equivalent to <a class="xref" href="libpq-async.html#LIBPQ-PQSENDQUERY"><code class="function">PQsendQuery</code></a> except that
  86        query parameters can be specified separately from the query string.
  87        The function's parameters are handled identically to
  88        <a class="xref" href="libpq-exec.html#LIBPQ-PQEXECPARAMS"><code class="function">PQexecParams</code></a>.  Like
  89        <a class="xref" href="libpq-exec.html#LIBPQ-PQEXECPARAMS"><code class="function">PQexecParams</code></a>, it allows only one command in the
  90        query string.
  91       </p></dd><dt id="LIBPQ-PQSENDPREPARE"><span class="term"><code class="function">PQsendPrepare</code><a id="id-1.7.3.11.4.19.3.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQSENDPREPARE" class="id_link">#</a></dt><dd><p>
  92        Sends a request to create a prepared statement with the given
  93        parameters, without waiting for completion.
  94 </p><pre class="synopsis">
  95 int PQsendPrepare(PGconn *conn,
  96                   const char *stmtName,
  97                   const char *query,
  98                   int nParams,
  99                   const Oid *paramTypes);
 100 </pre><p>
 101
 102        This is an asynchronous version of <a class="xref" href="libpq-exec.html#LIBPQ-PQPREPARE"><code class="function">PQprepare</code></a>: it
 103        returns 1 if it was able to dispatch the request, and 0 if not.
 104        After a successful call, call <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> to
 105        determine whether the server successfully created the prepared
 106        statement.  The function's parameters are handled identically to
 107        <a class="xref" href="libpq-exec.html#LIBPQ-PQPREPARE"><code class="function">PQprepare</code></a>.
 108       </p></dd><dt id="LIBPQ-PQSENDQUERYPREPARED"><span class="term"><code class="function">PQsendQueryPrepared</code><a id="id-1.7.3.11.4.19.4.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQSENDQUERYPREPARED" class="id_link">#</a></dt><dd><p>
 109        Sends a request to execute a prepared statement with given
 110        parameters, without waiting for the result(s).
 111 </p><pre class="synopsis">
 112 int PQsendQueryPrepared(PGconn *conn,
 113                         const char *stmtName,
 114                         int nParams,
 115                         const char * const *paramValues,
 116                         const int *paramLengths,
 117                         const int *paramFormats,
 118                         int resultFormat);
 119 </pre><p>
 120
 121        This is similar to <a class="xref" href="libpq-async.html#LIBPQ-PQSENDQUERYPARAMS"><code class="function">PQsendQueryParams</code></a>, but
 122        the command to be executed is specified by naming a
 123        previously-prepared statement, instead of giving a query string.
 124        The function's parameters are handled identically to
 125        <a class="xref" href="libpq-exec.html#LIBPQ-PQEXECPREPARED"><code class="function">PQexecPrepared</code></a>.
 126       </p></dd><dt id="LIBPQ-PQSENDDESCRIBEPREPARED"><span class="term"><code class="function">PQsendDescribePrepared</code><a id="id-1.7.3.11.4.19.5.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQSENDDESCRIBEPREPARED" class="id_link">#</a></dt><dd><p>
 127        Submits a request to obtain information about the specified
 128        prepared statement, without waiting for completion.
 129 </p><pre class="synopsis">
 130 int PQsendDescribePrepared(PGconn *conn, const char *stmtName);
 131 </pre><p>
 132
 133        This is an asynchronous version of <a class="xref" href="libpq-exec.html#LIBPQ-PQDESCRIBEPREPARED"><code class="function">PQdescribePrepared</code></a>:
 134        it returns 1 if it was able to dispatch the request, and 0 if not.
 135        After a successful call, call <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> to
 136        obtain the results.  The function's parameters are handled
 137        identically to <a class="xref" href="libpq-exec.html#LIBPQ-PQDESCRIBEPREPARED"><code class="function">PQdescribePrepared</code></a>.
 138       </p></dd><dt id="LIBPQ-PQSENDDESCRIBEPORTAL"><span class="term"><code class="function">PQsendDescribePortal</code><a id="id-1.7.3.11.4.19.6.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQSENDDESCRIBEPORTAL" class="id_link">#</a></dt><dd><p>
 139        Submits a request to obtain information about the specified
 140        portal, without waiting for completion.
 141 </p><pre class="synopsis">
 142 int PQsendDescribePortal(PGconn *conn, const char *portalName);
 143 </pre><p>
 144
 145        This is an asynchronous version of <a class="xref" href="libpq-exec.html#LIBPQ-PQDESCRIBEPORTAL"><code class="function">PQdescribePortal</code></a>:
 146        it returns 1 if it was able to dispatch the request, and 0 if not.
 147        After a successful call, call <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> to
 148        obtain the results.  The function's parameters are handled
 149        identically to <a class="xref" href="libpq-exec.html#LIBPQ-PQDESCRIBEPORTAL"><code class="function">PQdescribePortal</code></a>.
 150       </p></dd><dt id="LIBPQ-PQSENDCLOSEPREPARED"><span class="term"><code class="function">PQsendClosePrepared</code><a id="id-1.7.3.11.4.19.7.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQSENDCLOSEPREPARED" class="id_link">#</a></dt><dd><p>
 151        Submits a request to close the specified prepared statement, without
 152        waiting for completion.
 153 </p><pre class="synopsis">
 154 int PQsendClosePrepared(PGconn *conn, const char *stmtName);
 155 </pre><p>
 156
 157        This is an asynchronous version of <a class="xref" href="libpq-exec.html#LIBPQ-PQCLOSEPREPARED"><code class="function">PQclosePrepared</code></a>:
 158        it returns 1 if it was able to dispatch the request, and 0 if not.
 159        After a successful call, call <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> to
 160        obtain the results.  The function's parameters are handled
 161        identically to <a class="xref" href="libpq-exec.html#LIBPQ-PQCLOSEPREPARED"><code class="function">PQclosePrepared</code></a>.
 162       </p></dd><dt id="LIBPQ-PQSENDCLOSEPORTAL"><span class="term"><code class="function">PQsendClosePortal</code><a id="id-1.7.3.11.4.19.8.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQSENDCLOSEPORTAL" class="id_link">#</a></dt><dd><p>
 163        Submits a request to close specified portal, without waiting for
 164        completion.
 165 </p><pre class="synopsis">
 166 int PQsendClosePortal(PGconn *conn, const char *portalName);
 167 </pre><p>
 168
 169        This is an asynchronous version of <a class="xref" href="libpq-exec.html#LIBPQ-PQCLOSEPORTAL"><code class="function">PQclosePortal</code></a>:
 170        it returns 1 if it was able to dispatch the request, and 0 if not.
 171        After a successful call, call <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> to
 172        obtain the results.  The function's parameters are handled
 173        identically to <a class="xref" href="libpq-exec.html#LIBPQ-PQCLOSEPORTAL"><code class="function">PQclosePortal</code></a>.
 174       </p></dd><dt id="LIBPQ-PQGETRESULT"><span class="term"><code class="function">PQgetResult</code><a id="id-1.7.3.11.4.19.9.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQGETRESULT" class="id_link">#</a></dt><dd><p>
 175        Waits for the next result from a prior
 176        <a class="xref" href="libpq-async.html#LIBPQ-PQSENDQUERY"><code class="function">PQsendQuery</code></a>,
 177        <a class="xref" href="libpq-async.html#LIBPQ-PQSENDQUERYPARAMS"><code class="function">PQsendQueryParams</code></a>,
 178        <a class="xref" href="libpq-async.html#LIBPQ-PQSENDPREPARE"><code class="function">PQsendPrepare</code></a>,
 179        <a class="xref" href="libpq-async.html#LIBPQ-PQSENDQUERYPREPARED"><code class="function">PQsendQueryPrepared</code></a>,
 180        <a class="xref" href="libpq-async.html#LIBPQ-PQSENDDESCRIBEPREPARED"><code class="function">PQsendDescribePrepared</code></a>,
 181        <a class="xref" href="libpq-async.html#LIBPQ-PQSENDDESCRIBEPORTAL"><code class="function">PQsendDescribePortal</code></a>,
 182        <a class="xref" href="libpq-async.html#LIBPQ-PQSENDCLOSEPREPARED"><code class="function">PQsendClosePrepared</code></a>,
 183        <a class="xref" href="libpq-async.html#LIBPQ-PQSENDCLOSEPORTAL"><code class="function">PQsendClosePortal</code></a>,
 184        <a class="xref" href="libpq-pipeline-mode.html#LIBPQ-PQSENDPIPELINESYNC"><code class="function">PQsendPipelineSync</code></a>, or
 185        <a class="xref" href="libpq-pipeline-mode.html#LIBPQ-PQPIPELINESYNC"><code class="function">PQpipelineSync</code></a>
 186        call, and returns it.
 187        A null pointer is returned when the command is complete and there
 188        will be no more results.
 189 </p><pre class="synopsis">
 190 PGresult *PQgetResult(PGconn *conn);
 191 </pre><p>
 192       </p><p>
 193        <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> must be called repeatedly until
 194        it returns a null pointer, indicating that the command is done.
 195        (If called when no command is active,
 196        <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> will just return a null pointer
 197        at once.) Each non-null result from
 198        <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> should be processed using the
 199        same <code class="structname">PGresult</code> accessor functions previously
 200        described.  Don't forget to free each result object with
 201        <a class="xref" href="libpq-exec.html#LIBPQ-PQCLEAR"><code class="function">PQclear</code></a> when done with it.  Note that
 202        <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> will block only if a command is
 203        active and the necessary response data has not yet been read by
 204        <a class="xref" href="libpq-async.html#LIBPQ-PQCONSUMEINPUT"><code class="function">PQconsumeInput</code>
 205      </a>.
 206       </p><p>
 207        In pipeline mode, <code class="function">PQgetResult</code> will return normally
 208        unless an error occurs; for any subsequent query sent after the one
 209        that caused the error until (and excluding) the next synchronization point,
 210        a special result of type <code class="literal">PGRES_PIPELINE_ABORTED</code> will
 211        be returned, and a null pointer will be returned after it.
 212        When the pipeline synchronization point is reached, a result of type
 213        <code class="literal">PGRES_PIPELINE_SYNC</code> will be returned.
 214        The result of the next query after the synchronization point follows
 215        immediately (that is, no null pointer is returned after
 216        the synchronization point).
 217       </p><div class="note"><h3 class="title">Note</h3><p>
 218         Even when <a class="xref" href="libpq-exec.html#LIBPQ-PQRESULTSTATUS"><code class="function">PQresultStatus</code></a> indicates a fatal
 219         error, <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> should be called until it
 220         returns a null pointer, to allow <span class="application">libpq</span> to
 221         process the error information completely.
 222        </p></div></dd></dl></div><p>
 223   </p><p>
 224    Using <a class="xref" href="libpq-async.html#LIBPQ-PQSENDQUERY"><code class="function">PQsendQuery</code></a> and
 225    <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> solves one of
 226    <a class="xref" href="libpq-exec.html#LIBPQ-PQEXEC"><code class="function">PQexec</code></a>'s problems:  If a command string contains
 227    multiple <acronym class="acronym">SQL</acronym> commands, the results of those commands
 228    can be obtained individually.  (This allows a simple form of overlapped
 229    processing, by the way: the client can be handling the results of one
 230    command while the server is still working on later queries in the same
 231    command string.)
 232   </p><p>
 233    Another frequently-desired feature that can be obtained with
 234    <a class="xref" href="libpq-async.html#LIBPQ-PQSENDQUERY"><code class="function">PQsendQuery</code></a> and <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a>
 235    is retrieving large query results a limited number of rows at a time.
 236    This is discussed
 237    in <a class="xref" href="libpq-single-row-mode.html" title="32.6. Retrieving Query Results in Chunks">Section 32.6</a>.
 238   </p><p>
 239    By itself, calling <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a>
 240    will still cause the client to block until the server completes the
 241    next <acronym class="acronym">SQL</acronym> command.  This can be avoided by proper
 242    use of two more functions:
 243
 244    </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQCONSUMEINPUT"><span class="term"><code class="function">PQconsumeInput</code><a id="id-1.7.3.11.7.3.1.1.2" class="indexterm"></a>
 245      </span> <a href="#LIBPQ-PQCONSUMEINPUT" class="id_link">#</a></dt><dd><p>
 246        If input is available from the server, consume it.
 247 </p><pre class="synopsis">
 248 int PQconsumeInput(PGconn *conn);
 249 </pre><p>
 250       </p><p>
 251        <a class="xref" href="libpq-async.html#LIBPQ-PQCONSUMEINPUT"><code class="function">PQconsumeInput</code>
 252      </a> normally returns 1 indicating
 253        <span class="quote">“<span class="quote">no error</span>”</span>, but returns 0 if there was some kind of
 254        trouble (in which case <a class="xref" href="libpq-status.html#LIBPQ-PQERRORMESSAGE">
 255       <code class="function">PQerrorMessage</code>
 256
 257      </a> can be
 258        consulted).  Note that the result does not say whether any input
 259        data was actually collected. After calling
 260        <a class="xref" href="libpq-async.html#LIBPQ-PQCONSUMEINPUT"><code class="function">PQconsumeInput</code>
 261      </a>, the application can check
 262        <a class="xref" href="libpq-async.html#LIBPQ-PQISBUSY"><code class="function">PQisBusy</code></a> and/or
 263        <code class="function">PQnotifies</code> to see if their state has changed.
 264       </p><p>
 265        <a class="xref" href="libpq-async.html#LIBPQ-PQCONSUMEINPUT"><code class="function">PQconsumeInput</code>
 266      </a> can be called even if the
 267        application is not prepared to deal with a result or notification
 268        just yet.  The function will read available data and save it in
 269        a buffer, thereby causing a <code class="function">select()</code>
 270        read-ready indication to go away.  The application can thus use
 271        <a class="xref" href="libpq-async.html#LIBPQ-PQCONSUMEINPUT"><code class="function">PQconsumeInput</code>
 272      </a> to clear the
 273        <code class="function">select()</code> condition immediately, and then
 274        examine the results at leisure.
 275       </p></dd><dt id="LIBPQ-PQISBUSY"><span class="term"><code class="function">PQisBusy</code><a id="id-1.7.3.11.7.3.2.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQISBUSY" class="id_link">#</a></dt><dd><p>
 276        Returns 1 if a command is busy, that is,
 277        <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> would block waiting for input.
 278        A 0 return indicates that <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> can be
 279        called with assurance of not blocking.
 280 </p><pre class="synopsis">
 281 int PQisBusy(PGconn *conn);
 282 </pre><p>
 283       </p><p>
 284        <a class="xref" href="libpq-async.html#LIBPQ-PQISBUSY"><code class="function">PQisBusy</code></a> will not itself attempt to read data
 285        from the server; therefore <a class="xref" href="libpq-async.html#LIBPQ-PQCONSUMEINPUT"><code class="function">PQconsumeInput</code>
 286      </a>
 287        must be invoked first, or the busy state will never end.
 288       </p></dd></dl></div><p>
 289   </p><p>
 290    A typical application using these functions will have a main loop that
 291    uses <code class="function">select()</code> or <code class="function">poll()</code> to wait for
 292    all the conditions that it must respond to.  One of the conditions
 293    will be input available from the server, which in terms of
 294    <code class="function">select()</code> means readable data on the file
 295    descriptor identified by <a class="xref" href="libpq-status.html#LIBPQ-PQSOCKET"><code class="function">PQsocket</code></a>.  When the main
 296    loop detects input ready, it should call
 297    <a class="xref" href="libpq-async.html#LIBPQ-PQCONSUMEINPUT"><code class="function">PQconsumeInput</code>
 298      </a> to read the input.  It can then
 299    call <a class="xref" href="libpq-async.html#LIBPQ-PQISBUSY"><code class="function">PQisBusy</code></a>, followed by
 300    <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> if <a class="xref" href="libpq-async.html#LIBPQ-PQISBUSY"><code class="function">PQisBusy</code></a>
 301    returns false (0).  It can also call <code class="function">PQnotifies</code>
 302    to detect <code class="command">NOTIFY</code> messages (see <a class="xref" href="libpq-notify.html" title="32.9. Asynchronous Notification">Section 32.9</a>).
 303   </p><p>
 304    A client that uses
 305    <a class="xref" href="libpq-async.html#LIBPQ-PQSENDQUERY"><code class="function">PQsendQuery</code></a>/<a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a>
 306    can also attempt to cancel a command that is still being processed
 307    by the server; see <a class="xref" href="libpq-cancel.html" title="32.7. Canceling Queries in Progress">Section 32.7</a>.  But regardless of
 308    the return value of <a class="xref" href="libpq-cancel.html#LIBPQ-PQCANCELBLOCKING"><code class="function">PQcancelBlocking</code></a>, the application
 309    must continue with the normal result-reading sequence using
 310    <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a>.  A successful cancellation will
 311    simply cause the command to terminate sooner than it would have
 312    otherwise.
 313   </p><p>
 314    By using the functions described above, it is possible to avoid
 315    blocking while waiting for input from the database server.  However,
 316    it is still possible that the application will block waiting to send
 317    output to the server.  This is relatively uncommon but can happen if
 318    very long SQL commands or data values are sent.  (It is much more
 319    probable if the application sends data via <code class="command">COPY IN</code>,
 320    however.)  To prevent this possibility and achieve completely
 321    nonblocking database operation, the following additional functions
 322    can be used.
 323
 324    </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQSETNONBLOCKING"><span class="term"><code class="function">PQsetnonblocking</code><a id="id-1.7.3.11.10.2.1.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQSETNONBLOCKING" class="id_link">#</a></dt><dd><p>
 325        Sets the nonblocking status of the connection.
 326 </p><pre class="synopsis">
 327 int PQsetnonblocking(PGconn *conn, int arg);
 328 </pre><p>
 329       </p><p>
 330        Sets the state of the connection to nonblocking if
 331        <em class="parameter"><code>arg</code></em> is 1, or blocking if
 332        <em class="parameter"><code>arg</code></em> is 0.  Returns 0 if OK, -1 if error.
 333       </p><p>
 334        In the nonblocking state, successful calls to
 335        <a class="xref" href="libpq-async.html#LIBPQ-PQSENDQUERY"><code class="function">PQsendQuery</code></a>, <a class="xref" href="libpq-copy.html#LIBPQ-PQPUTLINE"><code class="function">PQputline</code></a>,
 336        <a class="xref" href="libpq-copy.html#LIBPQ-PQPUTNBYTES"><code class="function">PQputnbytes</code></a>, <a class="xref" href="libpq-copy.html#LIBPQ-PQPUTCOPYDATA"><code class="function">PQputCopyData</code></a>,
 337        and <a class="xref" href="libpq-copy.html#LIBPQ-PQENDCOPY"><code class="function">PQendcopy</code></a> will not block;  their changes
 338        are stored in the local output buffer until they are flushed.
 339        Unsuccessful calls will return an error and must be retried.
 340       </p><p>
 341        Note that <a class="xref" href="libpq-exec.html#LIBPQ-PQEXEC"><code class="function">PQexec</code></a> does not honor nonblocking
 342        mode; if it is called, it will act in blocking fashion anyway.
 343       </p></dd><dt id="LIBPQ-PQISNONBLOCKING"><span class="term"><code class="function">PQisnonblocking</code><a id="id-1.7.3.11.10.2.2.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQISNONBLOCKING" class="id_link">#</a></dt><dd><p>
 344        Returns the blocking status of the database connection.
 345 </p><pre class="synopsis">
 346 int PQisnonblocking(const PGconn *conn);
 347 </pre><p>
 348       </p><p>
 349        Returns 1 if the connection is set to nonblocking mode and 0 if
 350        blocking.
 351       </p></dd><dt id="LIBPQ-PQFLUSH"><span class="term"><code class="function">PQflush</code><a id="id-1.7.3.11.10.2.3.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQFLUSH" class="id_link">#</a></dt><dd><p>
 352        Attempts to flush any queued output data to the server.  Returns
 353        0 if successful (or if the send queue is empty), -1 if it failed
 354        for some reason, or 1 if it was unable to send all the data in
 355        the send queue yet (this case can only occur if the connection
 356        is nonblocking).
 357 </p><pre class="synopsis">
 358 int PQflush(PGconn *conn);
 359 </pre><p>
 360       </p></dd></dl></div><p>
 361   </p><p>
 362    After sending any command or data on a nonblocking connection, call
 363    <a class="xref" href="libpq-async.html#LIBPQ-PQFLUSH"><code class="function">PQflush</code></a>.  If it returns 1, wait for the socket
 364    to become read- or write-ready.  If it becomes write-ready, call
 365    <a class="xref" href="libpq-async.html#LIBPQ-PQFLUSH"><code class="function">PQflush</code></a> again.  If it becomes read-ready, call
 366    <a class="xref" href="libpq-async.html#LIBPQ-PQCONSUMEINPUT"><code class="function">PQconsumeInput</code>
 367      </a>, then call
 368    <a class="xref" href="libpq-async.html#LIBPQ-PQFLUSH"><code class="function">PQflush</code></a> again.  Repeat until
 369    <a class="xref" href="libpq-async.html#LIBPQ-PQFLUSH"><code class="function">PQflush</code></a> returns 0.  (It is necessary to check for
 370    read-ready and drain the input with <a class="xref" href="libpq-async.html#LIBPQ-PQCONSUMEINPUT"><code class="function">PQconsumeInput</code>
 371      </a>,
 372    because the server can block trying to send us data, e.g., NOTICE
 373    messages, and won't read our data until we read its.)  Once
 374    <a class="xref" href="libpq-async.html#LIBPQ-PQFLUSH"><code class="function">PQflush</code></a> returns 0, wait for the socket to be
 375    read-ready and then read the response as described above.
 376   </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="libpq-exec.html" title="32.3. Command Execution Functions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="libpq.html" title="Chapter 32. libpq — C Library">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="libpq-pipeline-mode.html" title="32.5. Pipeline Mode">Next</a></td></tr><tr><td width="40%" align="left" valign="top">32.3. Command Execution Functions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 32.5. Pipeline Mode</td></tr></table></div></body></html>