diff options
Diffstat (limited to 'doc/src/sgml/html/libpq-async.html')
| -rw-r--r-- | doc/src/sgml/html/libpq-async.html | 338 |
1 files changed, 338 insertions, 0 deletions
diff --git a/doc/src/sgml/html/libpq-async.html b/doc/src/sgml/html/libpq-async.html new file mode 100644 index 0000000..d0aafad --- /dev/null +++ b/doc/src/sgml/html/libpq-async.html @@ -0,0 +1,338 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!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 xmlns="http://www.w3.org/TR/xhtml1/transitional" 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 xmlns="http://www.w3.org/1999/xhtml" class="application">libpq</span> — C Library</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 14.5 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></hr></div><div class="sect1" id="LIBPQ-ASYNC"><div class="titlepage"><div><div><h2 class="title" style="clear: both">34.4. Asynchronous Command Processing</h2></div></div></div><a id="id-1.7.3.11.2" class="indexterm"></a><p> + The <a class="xref" href="libpq-exec.html#LIBPQ-PQEXEC"><code class="function">PQexec</code></a> function is adequate for submitting + commands in normal, synchronous applications. It has a few + deficiencies, however, that can be of importance to some users: + + </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> + <a class="xref" href="libpq-exec.html#LIBPQ-PQEXEC"><code class="function">PQexec</code></a> waits for the command to be completed. + The application might have other work to do (such as maintaining a + user interface), in which case it won't want to block waiting for + the response. + </p></li><li class="listitem"><p> + Since the execution of the client application is suspended while it + waits for the result, it is hard for the application to decide that + it would like to try to cancel the ongoing command. (It can be done + from a signal handler, but not otherwise.) + </p></li><li class="listitem"><p> + <a class="xref" href="libpq-exec.html#LIBPQ-PQEXEC"><code class="function">PQexec</code></a> can return only one + <code class="structname">PGresult</code> structure. If the submitted command + string contains multiple <acronym class="acronym">SQL</acronym> commands, all but + the last <code class="structname">PGresult</code> are discarded by + <a class="xref" href="libpq-exec.html#LIBPQ-PQEXEC"><code class="function">PQexec</code></a>. + </p></li><li class="listitem"><p> + <a class="xref" href="libpq-exec.html#LIBPQ-PQEXEC"><code class="function">PQexec</code></a> always collects the command's entire result, + buffering it in a single <code class="structname">PGresult</code>. While + this simplifies error-handling logic for the application, it can be + impractical for results containing many rows. + </p></li></ul></div><p> + </p><p> + Applications that do not like these limitations can instead use the + underlying functions that <a class="xref" href="libpq-exec.html#LIBPQ-PQEXEC"><code class="function">PQexec</code></a> is built from: + <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>. + There are also + <a class="xref" href="libpq-async.html#LIBPQ-PQSENDQUERYPARAMS"><code class="function">PQsendQueryParams</code></a>, + <a class="xref" href="libpq-async.html#LIBPQ-PQSENDPREPARE"><code class="function">PQsendPrepare</code></a>, + <a class="xref" href="libpq-async.html#LIBPQ-PQSENDQUERYPREPARED"><code class="function">PQsendQueryPrepared</code></a>, + <a class="xref" href="libpq-async.html#LIBPQ-PQSENDDESCRIBEPREPARED"><code class="function">PQsendDescribePrepared</code></a>, and + <a class="xref" href="libpq-async.html#LIBPQ-PQSENDDESCRIBEPORTAL"><code class="function">PQsendDescribePortal</code></a>, + which can be used with <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> to duplicate + the functionality of + <a class="xref" href="libpq-exec.html#LIBPQ-PQEXECPARAMS"><code class="function">PQexecParams</code></a>, + <a class="xref" href="libpq-exec.html#LIBPQ-PQPREPARE"><code class="function">PQprepare</code></a>, + <a class="xref" href="libpq-exec.html#LIBPQ-PQEXECPREPARED"><code class="function">PQexecPrepared</code></a>, + <a class="xref" href="libpq-exec.html#LIBPQ-PQDESCRIBEPREPARED"><code class="function">PQdescribePrepared</code></a>, and + <a class="xref" href="libpq-exec.html#LIBPQ-PQDESCRIBEPORTAL"><code class="function">PQdescribePortal</code></a> + respectively. + + </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></dt><dd><p> + Submits a command to the server without waiting for the result(s). + 1 is returned if the command was successfully dispatched and 0 if + not (in which case, use <a class="xref" href="libpq-status.html#LIBPQ-PQERRORMESSAGE"><code class="function">PQerrorMessage</code></a> to get more + information about the failure). +</p><pre class="synopsis"> +int PQsendQuery(PGconn *conn, const char *command); +</pre><p> + + After successfully calling <a class="xref" href="libpq-async.html#LIBPQ-PQSENDQUERY"><code class="function">PQsendQuery</code></a>, call + <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> one or more times to obtain the + results. <a class="xref" href="libpq-async.html#LIBPQ-PQSENDQUERY"><code class="function">PQsendQuery</code></a> cannot be called again + (on the same connection) until <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> + has returned a null pointer, indicating that the command is done. + </p><p> + In pipeline mode, command strings containing more than one SQL command + are disallowed. + </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></dt><dd><p> + Submits a command and separate parameters to the server without + waiting for the result(s). +</p><pre class="synopsis"> +int PQsendQueryParams(PGconn *conn, + const char *command, + int nParams, + const Oid *paramTypes, + const char * const *paramValues, + const int *paramLengths, + const int *paramFormats, + int resultFormat); +</pre><p> + + This is equivalent to <a class="xref" href="libpq-async.html#LIBPQ-PQSENDQUERY"><code class="function">PQsendQuery</code></a> except that + query parameters can be specified separately from the query string. + The function's parameters are handled identically to + <a class="xref" href="libpq-exec.html#LIBPQ-PQEXECPARAMS"><code class="function">PQexecParams</code></a>. Like + <a class="xref" href="libpq-exec.html#LIBPQ-PQEXECPARAMS"><code class="function">PQexecParams</code></a>, it allows only one command in the + query string. + </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></dt><dd><p> + Sends a request to create a prepared statement with the given + parameters, without waiting for completion. +</p><pre class="synopsis"> +int PQsendPrepare(PGconn *conn, + const char *stmtName, + const char *query, + int nParams, + const Oid *paramTypes); +</pre><p> + + This is an asynchronous version of <a class="xref" href="libpq-exec.html#LIBPQ-PQPREPARE"><code class="function">PQprepare</code></a>: it + returns 1 if it was able to dispatch the request, and 0 if not. + After a successful call, call <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> to + determine whether the server successfully created the prepared + statement. The function's parameters are handled identically to + <a class="xref" href="libpq-exec.html#LIBPQ-PQPREPARE"><code class="function">PQprepare</code></a>. + </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></dt><dd><p> + Sends a request to execute a prepared statement with given + parameters, without waiting for the result(s). +</p><pre class="synopsis"> +int PQsendQueryPrepared(PGconn *conn, + const char *stmtName, + int nParams, + const char * const *paramValues, + const int *paramLengths, + const int *paramFormats, + int resultFormat); +</pre><p> + + This is similar to <a class="xref" href="libpq-async.html#LIBPQ-PQSENDQUERYPARAMS"><code class="function">PQsendQueryParams</code></a>, but + the command to be executed is specified by naming a + previously-prepared statement, instead of giving a query string. + The function's parameters are handled identically to + <a class="xref" href="libpq-exec.html#LIBPQ-PQEXECPREPARED"><code class="function">PQexecPrepared</code></a>. + </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></dt><dd><p> + Submits a request to obtain information about the specified + prepared statement, without waiting for completion. +</p><pre class="synopsis"> +int PQsendDescribePrepared(PGconn *conn, const char *stmtName); +</pre><p> + + This is an asynchronous version of <a class="xref" href="libpq-exec.html#LIBPQ-PQDESCRIBEPREPARED"><code class="function">PQdescribePrepared</code></a>: + it returns 1 if it was able to dispatch the request, and 0 if not. + After a successful call, call <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> to + obtain the results. The function's parameters are handled + identically to <a class="xref" href="libpq-exec.html#LIBPQ-PQDESCRIBEPREPARED"><code class="function">PQdescribePrepared</code></a>. + </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></dt><dd><p> + Submits a request to obtain information about the specified + portal, without waiting for completion. +</p><pre class="synopsis"> +int PQsendDescribePortal(PGconn *conn, const char *portalName); +</pre><p> + + This is an asynchronous version of <a class="xref" href="libpq-exec.html#LIBPQ-PQDESCRIBEPORTAL"><code class="function">PQdescribePortal</code></a>: + it returns 1 if it was able to dispatch the request, and 0 if not. + After a successful call, call <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> to + obtain the results. The function's parameters are handled + identically to <a class="xref" href="libpq-exec.html#LIBPQ-PQDESCRIBEPORTAL"><code class="function">PQdescribePortal</code></a>. + </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></dt><dd><p> + Waits for the next result from a prior + <a class="xref" href="libpq-async.html#LIBPQ-PQSENDQUERY"><code class="function">PQsendQuery</code></a>, + <a class="xref" href="libpq-async.html#LIBPQ-PQSENDQUERYPARAMS"><code class="function">PQsendQueryParams</code></a>, + <a class="xref" href="libpq-async.html#LIBPQ-PQSENDPREPARE"><code class="function">PQsendPrepare</code></a>, + <a class="xref" href="libpq-async.html#LIBPQ-PQSENDQUERYPREPARED"><code class="function">PQsendQueryPrepared</code></a>, + <a class="xref" href="libpq-async.html#LIBPQ-PQSENDDESCRIBEPREPARED"><code class="function">PQsendDescribePrepared</code></a>, + <a class="xref" href="libpq-async.html#LIBPQ-PQSENDDESCRIBEPORTAL"><code class="function">PQsendDescribePortal</code></a>, or + <a class="xref" href="libpq-pipeline-mode.html#LIBPQ-PQPIPELINESYNC"><code class="function">PQpipelineSync</code></a> + call, and returns it. + A null pointer is returned when the command is complete and there + will be no more results. +</p><pre class="synopsis"> +PGresult *PQgetResult(PGconn *conn); +</pre><p> + </p><p> + <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> must be called repeatedly until + it returns a null pointer, indicating that the command is done. + (If called when no command is active, + <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> will just return a null pointer + at once.) Each non-null result from + <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> should be processed using the + same <code class="structname">PGresult</code> accessor functions previously + described. Don't forget to free each result object with + <a class="xref" href="libpq-exec.html#LIBPQ-PQCLEAR"><code class="function">PQclear</code></a> when done with it. Note that + <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> will block only if a command is + active and the necessary response data has not yet been read by + <a class="xref" href="libpq-async.html#LIBPQ-PQCONSUMEINPUT"><code class="function">PQconsumeInput</code> + </a>. + </p><p> + In pipeline mode, <code class="function">PQgetResult</code> will return normally + unless an error occurs; for any subsequent query sent after the one + that caused the error until (and excluding) the next synchronization point, + a special result of type <code class="literal">PGRES_PIPELINE_ABORTED</code> will + be returned, and a null pointer will be returned after it. + When the pipeline synchronization point is reached, a result of type + <code class="literal">PGRES_PIPELINE_SYNC</code> will be returned. + The result of the next query after the synchronization point follows + immediately (that is, no null pointer is returned after + the synchronization point.) + </p><div class="note"><h3 class="title">Note</h3><p> + Even when <a class="xref" href="libpq-exec.html#LIBPQ-PQRESULTSTATUS"><code class="function">PQresultStatus</code></a> indicates a fatal + error, <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> should be called until it + returns a null pointer, to allow <span class="application">libpq</span> to + process the error information completely. + </p></div></dd></dl></div><p> + </p><p> + Using <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> solves one of + <a class="xref" href="libpq-exec.html#LIBPQ-PQEXEC"><code class="function">PQexec</code></a>'s problems: If a command string contains + multiple <acronym class="acronym">SQL</acronym> commands, the results of those commands + can be obtained individually. (This allows a simple form of overlapped + processing, by the way: the client can be handling the results of one + command while the server is still working on later queries in the same + command string.) + </p><p> + Another frequently-desired feature that can be obtained with + <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> + is retrieving large query results a row at a time. This is discussed + in <a class="xref" href="libpq-single-row-mode.html" title="34.6. Retrieving Query Results Row-by-Row">Section 34.6</a>. + </p><p> + By itself, calling <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> + will still cause the client to block until the server completes the + next <acronym class="acronym">SQL</acronym> command. This can be avoided by proper + use of two more functions: + + </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> + </span></dt><dd><p> + If input is available from the server, consume it. +</p><pre class="synopsis"> +int PQconsumeInput(PGconn *conn); +</pre><p> + </p><p> + <a class="xref" href="libpq-async.html#LIBPQ-PQCONSUMEINPUT"><code class="function">PQconsumeInput</code> + </a> normally returns 1 indicating + <span class="quote">“<span class="quote">no error</span>”</span>, but returns 0 if there was some kind of + trouble (in which case <a class="xref" href="libpq-status.html#LIBPQ-PQERRORMESSAGE"><code class="function">PQerrorMessage</code></a> can be + consulted). Note that the result does not say whether any input + data was actually collected. After calling + <a class="xref" href="libpq-async.html#LIBPQ-PQCONSUMEINPUT"><code class="function">PQconsumeInput</code> + </a>, the application can check + <a class="xref" href="libpq-async.html#LIBPQ-PQISBUSY"><code class="function">PQisBusy</code></a> and/or + <code class="function">PQnotifies</code> to see if their state has changed. + </p><p> + <a class="xref" href="libpq-async.html#LIBPQ-PQCONSUMEINPUT"><code class="function">PQconsumeInput</code> + </a> can be called even if the + application is not prepared to deal with a result or notification + just yet. The function will read available data and save it in + a buffer, thereby causing a <code class="function">select()</code> + read-ready indication to go away. The application can thus use + <a class="xref" href="libpq-async.html#LIBPQ-PQCONSUMEINPUT"><code class="function">PQconsumeInput</code> + </a> to clear the + <code class="function">select()</code> condition immediately, and then + examine the results at leisure. + </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></dt><dd><p> + Returns 1 if a command is busy, that is, + <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> would block waiting for input. + A 0 return indicates that <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> can be + called with assurance of not blocking. +</p><pre class="synopsis"> +int PQisBusy(PGconn *conn); +</pre><p> + </p><p> + <a class="xref" href="libpq-async.html#LIBPQ-PQISBUSY"><code class="function">PQisBusy</code></a> will not itself attempt to read data + from the server; therefore <a class="xref" href="libpq-async.html#LIBPQ-PQCONSUMEINPUT"><code class="function">PQconsumeInput</code> + </a> + must be invoked first, or the busy state will never end. + </p></dd></dl></div><p> + </p><p> + A typical application using these functions will have a main loop that + uses <code class="function">select()</code> or <code class="function">poll()</code> to wait for + all the conditions that it must respond to. One of the conditions + will be input available from the server, which in terms of + <code class="function">select()</code> means readable data on the file + descriptor identified by <a class="xref" href="libpq-status.html#LIBPQ-PQSOCKET"><code class="function">PQsocket</code></a>. When the main + loop detects input ready, it should call + <a class="xref" href="libpq-async.html#LIBPQ-PQCONSUMEINPUT"><code class="function">PQconsumeInput</code> + </a> to read the input. It can then + call <a class="xref" href="libpq-async.html#LIBPQ-PQISBUSY"><code class="function">PQisBusy</code></a>, followed by + <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> + returns false (0). It can also call <code class="function">PQnotifies</code> + 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>). + </p><p> + A client that uses + <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> + can also attempt to cancel a command that is still being processed + by the server; see <a class="xref" href="libpq-cancel.html" title="34.7. Canceling Queries in Progress">Section 34.7</a>. But regardless of + the return value of <a class="xref" href="libpq-cancel.html#LIBPQ-PQCANCEL"><code class="function">PQcancel</code></a>, the application + must continue with the normal result-reading sequence using + <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a>. A successful cancellation will + simply cause the command to terminate sooner than it would have + otherwise. + </p><p> + By using the functions described above, it is possible to avoid + blocking while waiting for input from the database server. However, + it is still possible that the application will block waiting to send + output to the server. This is relatively uncommon but can happen if + very long SQL commands or data values are sent. (It is much more + probable if the application sends data via <code class="command">COPY IN</code>, + however.) To prevent this possibility and achieve completely + nonblocking database operation, the following additional functions + can be used. + + </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></dt><dd><p> + Sets the nonblocking status of the connection. +</p><pre class="synopsis"> +int PQsetnonblocking(PGconn *conn, int arg); +</pre><p> + </p><p> + Sets the state of the connection to nonblocking if + <em class="parameter"><code>arg</code></em> is 1, or blocking if + <em class="parameter"><code>arg</code></em> is 0. Returns 0 if OK, -1 if error. + </p><p> + In the nonblocking state, calls to + <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>, + <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>, + and <a class="xref" href="libpq-copy.html#LIBPQ-PQENDCOPY"><code class="function">PQendcopy</code></a> will not block but instead return + an error if they need to be called again. + </p><p> + Note that <a class="xref" href="libpq-exec.html#LIBPQ-PQEXEC"><code class="function">PQexec</code></a> does not honor nonblocking + mode; if it is called, it will act in blocking fashion anyway. + </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></dt><dd><p> + Returns the blocking status of the database connection. +</p><pre class="synopsis"> +int PQisnonblocking(const PGconn *conn); +</pre><p> + </p><p> + Returns 1 if the connection is set to nonblocking mode and 0 if + blocking. + </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></dt><dd><p> + Attempts to flush any queued output data to the server. Returns + 0 if successful (or if the send queue is empty), -1 if it failed + for some reason, or 1 if it was unable to send all the data in + the send queue yet (this case can only occur if the connection + is nonblocking). +</p><pre class="synopsis"> +int PQflush(PGconn *conn); +</pre><p> + </p></dd></dl></div><p> + </p><p> + After sending any command or data on a nonblocking connection, call + <a class="xref" href="libpq-async.html#LIBPQ-PQFLUSH"><code class="function">PQflush</code></a>. If it returns 1, wait for the socket + to become read- or write-ready. If it becomes write-ready, call + <a class="xref" href="libpq-async.html#LIBPQ-PQFLUSH"><code class="function">PQflush</code></a> again. If it becomes read-ready, call + <a class="xref" href="libpq-async.html#LIBPQ-PQCONSUMEINPUT"><code class="function">PQconsumeInput</code> + </a>, then call + <a class="xref" href="libpq-async.html#LIBPQ-PQFLUSH"><code class="function">PQflush</code></a> again. Repeat until + <a class="xref" href="libpq-async.html#LIBPQ-PQFLUSH"><code class="function">PQflush</code></a> returns 0. (It is necessary to check for + read-ready and drain the input with <a class="xref" href="libpq-async.html#LIBPQ-PQCONSUMEINPUT"><code class="function">PQconsumeInput</code> + </a>, + because the server can block trying to send us data, e.g., NOTICE + messages, and won't read our data until we read its.) Once + <a class="xref" href="libpq-async.html#LIBPQ-PQFLUSH"><code class="function">PQflush</code></a> returns 0, wait for the socket to be + read-ready and then read the response as described above. + </p></div><div xmlns="http://www.w3.org/TR/xhtml1/transitional" class="navfooter"><hr></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 14.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 34.5. Pipeline Mode</td></tr></table></div></body></html>
\ No newline at end of file |