Team Ai
Datasetpublic

codekingpro/portable-devtools

sourceHugging Faceupdated 5mo agoView on Hugging Face
1likes14kdownloads
libpq-async.html338 linesDownload Raw Back to 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>34.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="34.3. Command Execution Functions" /><link rel="next" href="libpq-pipeline-mode.html" title="34.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">34.4. Asynchronous Command Processing</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="libpq-exec.html" title="34.3. Command Execution Functions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><th width="60%" align="center">Chapter 34. <span class="application">libpq</span> — C Library</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 16.3 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="libpq-pipeline-mode.html" title="34.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">34.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 submitting4   commands in normal, synchronous applications.  It has a few5   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 a10      user interface), in which case it won't want to block waiting for11      the response.12     </p></li><li class="listitem"><p>13      Since the execution of the client application is suspended while it14      waits for the result, it is hard for the application to decide that15      it would like to try to cancel the ongoing command.  (It can be done16      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 one19      <code class="structname">PGresult</code> structure.  If the submitted command20      string contains multiple <acronym class="acronym">SQL</acronym> commands, all but21      the last <code class="structname">PGresult</code> are discarded by22      <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>.  While26      this simplifies error-handling logic for the application, it can be27      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 the31   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 also34   <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>, and38   <a class="xref" href="libpq-async.html#LIBPQ-PQSENDDESCRIBEPORTAL"><code class="function">PQsendDescribePortal</code></a>,39   which can be used with <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> to duplicate40   the functionality of41   <a class="xref" href="libpq-exec.html#LIBPQ-PQEXECPARAMS"><code class="function">PQexecParams</code></a>,42   <a class="xref" href="libpq-exec.html#LIBPQ-PQPREPARE"><code class="function">PQprepare</code></a>,43   <a class="xref" href="libpq-exec.html#LIBPQ-PQEXECPREPARED"><code class="function">PQexecPrepared</code></a>,44   <a class="xref" href="libpq-exec.html#LIBPQ-PQDESCRIBEPREPARED"><code class="function">PQdescribePrepared</code></a>, and45   <a class="xref" href="libpq-exec.html#LIBPQ-PQDESCRIBEPORTAL"><code class="function">PQdescribePortal</code></a>46   respectively.47 48   </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.15.1.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQSENDQUERY" class="id_link">#</a></dt><dd><p>49       Submits a command to the server without waiting for the result(s).50       1 is returned if the command was successfully dispatched and 0 if51       not (in which case, use <a class="xref" href="libpq-status.html#LIBPQ-PQERRORMESSAGE"><code class="function">PQerrorMessage</code></a> to get more52       information about the failure).53</p><pre class="synopsis">54int PQsendQuery(PGconn *conn, const char *command);55</pre><p>56 57       After successfully calling <a class="xref" href="libpq-async.html#LIBPQ-PQSENDQUERY"><code class="function">PQsendQuery</code></a>, call58       <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> one or more times to obtain the59       results.  <a class="xref" href="libpq-async.html#LIBPQ-PQSENDQUERY"><code class="function">PQsendQuery</code></a> cannot be called again60       (on the same connection) until <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a>61       has returned a null pointer, indicating that the command is done.62      </p><p>63       In pipeline mode, this function is disallowed.64      </p></dd><dt id="LIBPQ-PQSENDQUERYPARAMS"><span class="term"><code class="function">PQsendQueryParams</code><a id="id-1.7.3.11.4.15.2.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQSENDQUERYPARAMS" class="id_link">#</a></dt><dd><p>65       Submits a command and separate parameters to the server without66       waiting for the result(s).67</p><pre class="synopsis">68int PQsendQueryParams(PGconn *conn,69                      const char *command,70                      int nParams,71                      const Oid *paramTypes,72                      const char * const *paramValues,73                      const int *paramLengths,74                      const int *paramFormats,75                      int resultFormat);76</pre><p>77 78       This is equivalent to <a class="xref" href="libpq-async.html#LIBPQ-PQSENDQUERY"><code class="function">PQsendQuery</code></a> except that79       query parameters can be specified separately from the query string.80       The function's parameters are handled identically to81       <a class="xref" href="libpq-exec.html#LIBPQ-PQEXECPARAMS"><code class="function">PQexecParams</code></a>.  Like82       <a class="xref" href="libpq-exec.html#LIBPQ-PQEXECPARAMS"><code class="function">PQexecParams</code></a>, it allows only one command in the83       query string.84      </p></dd><dt id="LIBPQ-PQSENDPREPARE"><span class="term"><code class="function">PQsendPrepare</code><a id="id-1.7.3.11.4.15.3.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQSENDPREPARE" class="id_link">#</a></dt><dd><p>85       Sends a request to create a prepared statement with the given86       parameters, without waiting for completion.87</p><pre class="synopsis">88int PQsendPrepare(PGconn *conn,89                  const char *stmtName,90                  const char *query,91                  int nParams,92                  const Oid *paramTypes);93</pre><p>94 95       This is an asynchronous version of <a class="xref" href="libpq-exec.html#LIBPQ-PQPREPARE"><code class="function">PQprepare</code></a>: it96       returns 1 if it was able to dispatch the request, and 0 if not.97       After a successful call, call <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> to98       determine whether the server successfully created the prepared99       statement.  The function's parameters are handled identically to100       <a class="xref" href="libpq-exec.html#LIBPQ-PQPREPARE"><code class="function">PQprepare</code></a>.101      </p></dd><dt id="LIBPQ-PQSENDQUERYPREPARED"><span class="term"><code class="function">PQsendQueryPrepared</code><a id="id-1.7.3.11.4.15.4.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQSENDQUERYPREPARED" class="id_link">#</a></dt><dd><p>102       Sends a request to execute a prepared statement with given103       parameters, without waiting for the result(s).104</p><pre class="synopsis">105int PQsendQueryPrepared(PGconn *conn,106                        const char *stmtName,107                        int nParams,108                        const char * const *paramValues,109                        const int *paramLengths,110                        const int *paramFormats,111                        int resultFormat);112</pre><p>113 114       This is similar to <a class="xref" href="libpq-async.html#LIBPQ-PQSENDQUERYPARAMS"><code class="function">PQsendQueryParams</code></a>, but115       the command to be executed is specified by naming a116       previously-prepared statement, instead of giving a query string.117       The function's parameters are handled identically to118       <a class="xref" href="libpq-exec.html#LIBPQ-PQEXECPREPARED"><code class="function">PQexecPrepared</code></a>.119      </p></dd><dt id="LIBPQ-PQSENDDESCRIBEPREPARED"><span class="term"><code class="function">PQsendDescribePrepared</code><a id="id-1.7.3.11.4.15.5.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQSENDDESCRIBEPREPARED" class="id_link">#</a></dt><dd><p>120       Submits a request to obtain information about the specified121       prepared statement, without waiting for completion.122</p><pre class="synopsis">123int PQsendDescribePrepared(PGconn *conn, const char *stmtName);124</pre><p>125 126       This is an asynchronous version of <a class="xref" href="libpq-exec.html#LIBPQ-PQDESCRIBEPREPARED"><code class="function">PQdescribePrepared</code></a>:127       it returns 1 if it was able to dispatch the request, and 0 if not.128       After a successful call, call <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> to129       obtain the results.  The function's parameters are handled130       identically to <a class="xref" href="libpq-exec.html#LIBPQ-PQDESCRIBEPREPARED"><code class="function">PQdescribePrepared</code></a>.131      </p></dd><dt id="LIBPQ-PQSENDDESCRIBEPORTAL"><span class="term"><code class="function">PQsendDescribePortal</code><a id="id-1.7.3.11.4.15.6.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQSENDDESCRIBEPORTAL" class="id_link">#</a></dt><dd><p>132       Submits a request to obtain information about the specified133       portal, without waiting for completion.134</p><pre class="synopsis">135int PQsendDescribePortal(PGconn *conn, const char *portalName);136</pre><p>137 138       This is an asynchronous version of <a class="xref" href="libpq-exec.html#LIBPQ-PQDESCRIBEPORTAL"><code class="function">PQdescribePortal</code></a>:139       it returns 1 if it was able to dispatch the request, and 0 if not.140       After a successful call, call <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> to141       obtain the results.  The function's parameters are handled142       identically to <a class="xref" href="libpq-exec.html#LIBPQ-PQDESCRIBEPORTAL"><code class="function">PQdescribePortal</code></a>.143      </p></dd><dt id="LIBPQ-PQGETRESULT"><span class="term"><code class="function">PQgetResult</code><a id="id-1.7.3.11.4.15.7.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQGETRESULT" class="id_link">#</a></dt><dd><p>144       Waits for the next result from a prior145       <a class="xref" href="libpq-async.html#LIBPQ-PQSENDQUERY"><code class="function">PQsendQuery</code></a>,146       <a class="xref" href="libpq-async.html#LIBPQ-PQSENDQUERYPARAMS"><code class="function">PQsendQueryParams</code></a>,147       <a class="xref" href="libpq-async.html#LIBPQ-PQSENDPREPARE"><code class="function">PQsendPrepare</code></a>,148       <a class="xref" href="libpq-async.html#LIBPQ-PQSENDQUERYPREPARED"><code class="function">PQsendQueryPrepared</code></a>,149       <a class="xref" href="libpq-async.html#LIBPQ-PQSENDDESCRIBEPREPARED"><code class="function">PQsendDescribePrepared</code></a>,150       <a class="xref" href="libpq-async.html#LIBPQ-PQSENDDESCRIBEPORTAL"><code class="function">PQsendDescribePortal</code></a>, or151       <a class="xref" href="libpq-pipeline-mode.html#LIBPQ-PQPIPELINESYNC"><code class="function">PQpipelineSync</code></a>152       call, and returns it.153       A null pointer is returned when the command is complete and there154       will be no more results.155</p><pre class="synopsis">156PGresult *PQgetResult(PGconn *conn);157</pre><p>158      </p><p>159       <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> must be called repeatedly until160       it returns a null pointer, indicating that the command is done.161       (If called when no command is active,162       <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> will just return a null pointer163       at once.) Each non-null result from164       <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> should be processed using the165       same <code class="structname">PGresult</code> accessor functions previously166       described.  Don't forget to free each result object with167       <a class="xref" href="libpq-exec.html#LIBPQ-PQCLEAR"><code class="function">PQclear</code></a> when done with it.  Note that168       <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> will block only if a command is169       active and the necessary response data has not yet been read by170       <a class="xref" href="libpq-async.html#LIBPQ-PQCONSUMEINPUT"><code class="function">PQconsumeInput</code>171     </a>.172      </p><p>173       In pipeline mode, <code class="function">PQgetResult</code> will return normally174       unless an error occurs; for any subsequent query sent after the one175       that caused the error until (and excluding) the next synchronization point,176       a special result of type <code class="literal">PGRES_PIPELINE_ABORTED</code> will177       be returned, and a null pointer will be returned after it.178       When the pipeline synchronization point is reached, a result of type179       <code class="literal">PGRES_PIPELINE_SYNC</code> will be returned.180       The result of the next query after the synchronization point follows181       immediately (that is, no null pointer is returned after182       the synchronization point.)183      </p><div class="note"><h3 class="title">Note</h3><p>184        Even when <a class="xref" href="libpq-exec.html#LIBPQ-PQRESULTSTATUS"><code class="function">PQresultStatus</code></a> indicates a fatal185        error, <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> should be called until it186        returns a null pointer, to allow <span class="application">libpq</span> to187        process the error information completely.188       </p></div></dd></dl></div><p>189  </p><p>190   Using <a class="xref" href="libpq-async.html#LIBPQ-PQSENDQUERY"><code class="function">PQsendQuery</code></a> and191   <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> solves one of192   <a class="xref" href="libpq-exec.html#LIBPQ-PQEXEC"><code class="function">PQexec</code></a>'s problems:  If a command string contains193   multiple <acronym class="acronym">SQL</acronym> commands, the results of those commands194   can be obtained individually.  (This allows a simple form of overlapped195   processing, by the way: the client can be handling the results of one196   command while the server is still working on later queries in the same197   command string.)198  </p><p>199   Another frequently-desired feature that can be obtained with200   <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>201   is retrieving large query results a row at a time.  This is discussed202   in <a class="xref" href="libpq-single-row-mode.html" title="34.6. Retrieving Query Results Row-by-Row">Section 34.6</a>.203  </p><p>204   By itself, calling <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a>205   will still cause the client to block until the server completes the206   next <acronym class="acronym">SQL</acronym> command.  This can be avoided by proper207   use of two more functions:208 209   </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>210     </span> <a href="#LIBPQ-PQCONSUMEINPUT" class="id_link">#</a></dt><dd><p>211       If input is available from the server, consume it.212</p><pre class="synopsis">213int PQconsumeInput(PGconn *conn);214</pre><p>215      </p><p>216       <a class="xref" href="libpq-async.html#LIBPQ-PQCONSUMEINPUT"><code class="function">PQconsumeInput</code>217     </a> normally returns 1 indicating218       <span class="quote">“<span class="quote">no error</span>”</span>, but returns 0 if there was some kind of219       trouble (in which case <a class="xref" href="libpq-status.html#LIBPQ-PQERRORMESSAGE"><code class="function">PQerrorMessage</code></a> can be220       consulted).  Note that the result does not say whether any input221       data was actually collected. After calling222       <a class="xref" href="libpq-async.html#LIBPQ-PQCONSUMEINPUT"><code class="function">PQconsumeInput</code>223     </a>, the application can check224       <a class="xref" href="libpq-async.html#LIBPQ-PQISBUSY"><code class="function">PQisBusy</code></a> and/or225       <code class="function">PQnotifies</code> to see if their state has changed.226      </p><p>227       <a class="xref" href="libpq-async.html#LIBPQ-PQCONSUMEINPUT"><code class="function">PQconsumeInput</code>228     </a> can be called even if the229       application is not prepared to deal with a result or notification230       just yet.  The function will read available data and save it in231       a buffer, thereby causing a <code class="function">select()</code>232       read-ready indication to go away.  The application can thus use233       <a class="xref" href="libpq-async.html#LIBPQ-PQCONSUMEINPUT"><code class="function">PQconsumeInput</code>234     </a> to clear the235       <code class="function">select()</code> condition immediately, and then236       examine the results at leisure.237      </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>238       Returns 1 if a command is busy, that is,239       <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> would block waiting for input.240       A 0 return indicates that <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> can be241       called with assurance of not blocking.242</p><pre class="synopsis">243int PQisBusy(PGconn *conn);244</pre><p>245      </p><p>246       <a class="xref" href="libpq-async.html#LIBPQ-PQISBUSY"><code class="function">PQisBusy</code></a> will not itself attempt to read data247       from the server; therefore <a class="xref" href="libpq-async.html#LIBPQ-PQCONSUMEINPUT"><code class="function">PQconsumeInput</code>248     </a>249       must be invoked first, or the busy state will never end.250      </p></dd></dl></div><p>251  </p><p>252   A typical application using these functions will have a main loop that253   uses <code class="function">select()</code> or <code class="function">poll()</code> to wait for254   all the conditions that it must respond to.  One of the conditions255   will be input available from the server, which in terms of256   <code class="function">select()</code> means readable data on the file257   descriptor identified by <a class="xref" href="libpq-status.html#LIBPQ-PQSOCKET"><code class="function">PQsocket</code></a>.  When the main258   loop detects input ready, it should call259   <a class="xref" href="libpq-async.html#LIBPQ-PQCONSUMEINPUT"><code class="function">PQconsumeInput</code>260     </a> to read the input.  It can then261   call <a class="xref" href="libpq-async.html#LIBPQ-PQISBUSY"><code class="function">PQisBusy</code></a>, followed by262   <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>263   returns false (0).  It can also call <code class="function">PQnotifies</code>264   to detect <code class="command">NOTIFY</code> messages (see <a class="xref" href="libpq-notify.html" title="34.9. Asynchronous Notification">Section 34.9</a>).265  </p><p>266   A client that uses267   <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>268   can also attempt to cancel a command that is still being processed269   by the server; see <a class="xref" href="libpq-cancel.html" title="34.7. Canceling Queries in Progress">Section 34.7</a>.  But regardless of270   the return value of <a class="xref" href="libpq-cancel.html#LIBPQ-PQCANCEL"><code class="function">PQcancel</code></a>, the application271   must continue with the normal result-reading sequence using272   <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a>.  A successful cancellation will273   simply cause the command to terminate sooner than it would have274   otherwise.275  </p><p>276   By using the functions described above, it is possible to avoid277   blocking while waiting for input from the database server.  However,278   it is still possible that the application will block waiting to send279   output to the server.  This is relatively uncommon but can happen if280   very long SQL commands or data values are sent.  (It is much more281   probable if the application sends data via <code class="command">COPY IN</code>,282   however.)  To prevent this possibility and achieve completely283   nonblocking database operation, the following additional functions284   can be used.285 286   </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>287       Sets the nonblocking status of the connection.288</p><pre class="synopsis">289int PQsetnonblocking(PGconn *conn, int arg);290</pre><p>291      </p><p>292       Sets the state of the connection to nonblocking if293       <em class="parameter"><code>arg</code></em> is 1, or blocking if294       <em class="parameter"><code>arg</code></em> is 0.  Returns 0 if OK, -1 if error.295      </p><p>296       In the nonblocking state, successful calls to297       <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>,298       <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>,299       and <a class="xref" href="libpq-copy.html#LIBPQ-PQENDCOPY"><code class="function">PQendcopy</code></a> will not block;  their changes300       are stored in the local output buffer until they are flushed.301       Unsuccessful calls will return an error and must be retried.302      </p><p>303       Note that <a class="xref" href="libpq-exec.html#LIBPQ-PQEXEC"><code class="function">PQexec</code></a> does not honor nonblocking304       mode; if it is called, it will act in blocking fashion anyway.305      </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>306       Returns the blocking status of the database connection.307</p><pre class="synopsis">308int PQisnonblocking(const PGconn *conn);309</pre><p>310      </p><p>311       Returns 1 if the connection is set to nonblocking mode and 0 if312       blocking.313      </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>314       Attempts to flush any queued output data to the server.  Returns315       0 if successful (or if the send queue is empty), -1 if it failed316       for some reason, or 1 if it was unable to send all the data in317       the send queue yet (this case can only occur if the connection318       is nonblocking).319</p><pre class="synopsis">320int PQflush(PGconn *conn);321</pre><p>322      </p></dd></dl></div><p>323  </p><p>324   After sending any command or data on a nonblocking connection, call325   <a class="xref" href="libpq-async.html#LIBPQ-PQFLUSH"><code class="function">PQflush</code></a>.  If it returns 1, wait for the socket326   to become read- or write-ready.  If it becomes write-ready, call327   <a class="xref" href="libpq-async.html#LIBPQ-PQFLUSH"><code class="function">PQflush</code></a> again.  If it becomes read-ready, call328   <a class="xref" href="libpq-async.html#LIBPQ-PQCONSUMEINPUT"><code class="function">PQconsumeInput</code>329     </a>, then call330   <a class="xref" href="libpq-async.html#LIBPQ-PQFLUSH"><code class="function">PQflush</code></a> again.  Repeat until331   <a class="xref" href="libpq-async.html#LIBPQ-PQFLUSH"><code class="function">PQflush</code></a> returns 0.  (It is necessary to check for332   read-ready and drain the input with <a class="xref" href="libpq-async.html#LIBPQ-PQCONSUMEINPUT"><code class="function">PQconsumeInput</code>333     </a>,334   because the server can block trying to send us data, e.g., NOTICE335   messages, and won't read our data until we read its.)  Once336   <a class="xref" href="libpq-async.html#LIBPQ-PQFLUSH"><code class="function">PQflush</code></a> returns 0, wait for the socket to be337   read-ready and then read the response as described above.338  </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="34.3. Command Execution Functions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="libpq-pipeline-mode.html" title="34.5. Pipeline Mode">Next</a></td></tr><tr><td width="40%" align="left" valign="top">34.3. Command Execution Functions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 16.3 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 34.5. Pipeline Mode</td></tr></table></div></body></html>
codekingpro/portable-devtools · Team Ai