begriffs open source - ai-pg/blob - full-docs/txt/libpq-async.txt

   1
   2 32.4. Asynchronous Command Processing #
   3
   4    The PQexec function is adequate for submitting commands in normal,
   5    synchronous applications. It has a few deficiencies, however, that can
   6    be of importance to some users:
   7      * PQexec waits for the command to be completed. The application might
   8        have other work to do (such as maintaining a user interface), in
   9        which case it won't want to block waiting for the response.
  10      * Since the execution of the client application is suspended while it
  11        waits for the result, it is hard for the application to decide that
  12        it would like to try to cancel the ongoing command. (It can be done
  13        from a signal handler, but not otherwise.)
  14      * PQexec can return only one PGresult structure. If the submitted
  15        command string contains multiple SQL commands, all but the last
  16        PGresult are discarded by PQexec.
  17      * PQexec always collects the command's entire result, buffering it in
  18        a single PGresult. While this simplifies error-handling logic for
  19        the application, it can be impractical for results containing many
  20        rows.
  21
  22    Applications that do not like these limitations can instead use the
  23    underlying functions that PQexec is built from: PQsendQuery and
  24    PQgetResult. There are also PQsendQueryParams, PQsendPrepare,
  25    PQsendQueryPrepared, PQsendDescribePrepared, PQsendDescribePortal,
  26    PQsendClosePrepared, and PQsendClosePortal, which can be used with
  27    PQgetResult to duplicate the functionality of PQexecParams, PQprepare,
  28    PQexecPrepared, PQdescribePrepared, PQdescribePortal, PQclosePrepared,
  29    and PQclosePortal respectively.
  30
  31    PQsendQuery #
  32           Submits a command to the server without waiting for the
  33           result(s). 1 is returned if the command was successfully
  34           dispatched and 0 if not (in which case, use PQerrorMessage to
  35           get more information about the failure).
  36
  37 int PQsendQuery(PGconn *conn, const char *command);
  38
  39           After successfully calling PQsendQuery, call PQgetResult one or
  40           more times to obtain the results. PQsendQuery cannot be called
  41           again (on the same connection) until PQgetResult has returned a
  42           null pointer, indicating that the command is done.
  43
  44           In pipeline mode, this function is disallowed.
  45
  46    PQsendQueryParams #
  47           Submits a command and separate parameters to the server without
  48           waiting for the result(s).
  49
  50 int PQsendQueryParams(PGconn *conn,
  51                       const char *command,
  52                       int nParams,
  53                       const Oid *paramTypes,
  54                       const char * const *paramValues,
  55                       const int *paramLengths,
  56                       const int *paramFormats,
  57                       int resultFormat);
  58
  59           This is equivalent to PQsendQuery except that query parameters
  60           can be specified separately from the query string. The
  61           function's parameters are handled identically to PQexecParams.
  62           Like PQexecParams, it allows only one command in the query
  63           string.
  64
  65    PQsendPrepare #
  66           Sends a request to create a prepared statement with the given
  67           parameters, without waiting for completion.
  68
  69 int PQsendPrepare(PGconn *conn,
  70                   const char *stmtName,
  71                   const char *query,
  72                   int nParams,
  73                   const Oid *paramTypes);
  74
  75           This is an asynchronous version of PQprepare: it returns 1 if it
  76           was able to dispatch the request, and 0 if not. After a
  77           successful call, call PQgetResult to determine whether the
  78           server successfully created the prepared statement. The
  79           function's parameters are handled identically to PQprepare.
  80
  81    PQsendQueryPrepared #
  82           Sends a request to execute a prepared statement with given
  83           parameters, without waiting for the result(s).
  84
  85 int PQsendQueryPrepared(PGconn *conn,
  86                         const char *stmtName,
  87                         int nParams,
  88                         const char * const *paramValues,
  89                         const int *paramLengths,
  90                         const int *paramFormats,
  91                         int resultFormat);
  92
  93           This is similar to PQsendQueryParams, but the command to be
  94           executed is specified by naming a previously-prepared statement,
  95           instead of giving a query string. The function's parameters are
  96           handled identically to PQexecPrepared.
  97
  98    PQsendDescribePrepared #
  99           Submits a request to obtain information about the specified
 100           prepared statement, without waiting for completion.
 101
 102 int PQsendDescribePrepared(PGconn *conn, const char *stmtName);
 103
 104           This is an asynchronous version of PQdescribePrepared: it
 105           returns 1 if it was able to dispatch the request, and 0 if not.
 106           After a successful call, call PQgetResult to obtain the results.
 107           The function's parameters are handled identically to
 108           PQdescribePrepared.
 109
 110    PQsendDescribePortal #
 111           Submits a request to obtain information about the specified
 112           portal, without waiting for completion.
 113
 114 int PQsendDescribePortal(PGconn *conn, const char *portalName);
 115
 116           This is an asynchronous version of PQdescribePortal: it returns
 117           1 if it was able to dispatch the request, and 0 if not. After a
 118           successful call, call PQgetResult to obtain the results. The
 119           function's parameters are handled identically to
 120           PQdescribePortal.
 121
 122    PQsendClosePrepared #
 123           Submits a request to close the specified prepared statement,
 124           without waiting for completion.
 125
 126 int PQsendClosePrepared(PGconn *conn, const char *stmtName);
 127
 128           This is an asynchronous version of PQclosePrepared: it returns 1
 129           if it was able to dispatch the request, and 0 if not. After a
 130           successful call, call PQgetResult to obtain the results. The
 131           function's parameters are handled identically to
 132           PQclosePrepared.
 133
 134    PQsendClosePortal #
 135           Submits a request to close specified portal, without waiting for
 136           completion.
 137
 138 int PQsendClosePortal(PGconn *conn, const char *portalName);
 139
 140           This is an asynchronous version of PQclosePortal: it returns 1
 141           if it was able to dispatch the request, and 0 if not. After a
 142           successful call, call PQgetResult to obtain the results. The
 143           function's parameters are handled identically to PQclosePortal.
 144
 145    PQgetResult #
 146           Waits for the next result from a prior PQsendQuery,
 147           PQsendQueryParams, PQsendPrepare, PQsendQueryPrepared,
 148           PQsendDescribePrepared, PQsendDescribePortal,
 149           PQsendClosePrepared, PQsendClosePortal, PQsendPipelineSync, or
 150           PQpipelineSync call, and returns it. A null pointer is returned
 151           when the command is complete and there will be no more results.
 152
 153 PGresult *PQgetResult(PGconn *conn);
 154
 155           PQgetResult must be called repeatedly until it returns a null
 156           pointer, indicating that the command is done. (If called when no
 157           command is active, PQgetResult will just return a null pointer
 158           at once.) Each non-null result from PQgetResult should be
 159           processed using the same PGresult accessor functions previously
 160           described. Don't forget to free each result object with PQclear
 161           when done with it. Note that PQgetResult will block only if a
 162           command is active and the necessary response data has not yet
 163           been read by PQconsumeInput .
 164
 165           In pipeline mode, PQgetResult will return normally unless an
 166           error occurs; for any subsequent query sent after the one that
 167           caused the error until (and excluding) the next synchronization
 168           point, a special result of type PGRES_PIPELINE_ABORTED will be
 169           returned, and a null pointer will be returned after it. When the
 170           pipeline synchronization point is reached, a result of type
 171           PGRES_PIPELINE_SYNC will be returned. The result of the next
 172           query after the synchronization point follows immediately (that
 173           is, no null pointer is returned after the synchronization
 174           point).
 175
 176 Note
 177
 178           Even when PQresultStatus indicates a fatal error, PQgetResult
 179           should be called until it returns a null pointer, to allow libpq
 180           to process the error information completely.
 181
 182    Using PQsendQuery and PQgetResult solves one of PQexec's problems: If a
 183    command string contains multiple SQL commands, the results of those
 184    commands can be obtained individually. (This allows a simple form of
 185    overlapped processing, by the way: the client can be handling the
 186    results of one command while the server is still working on later
 187    queries in the same command string.)
 188
 189    Another frequently-desired feature that can be obtained with
 190    PQsendQuery and PQgetResult is retrieving large query results a limited
 191    number of rows at a time. This is discussed in Section 32.6.
 192
 193    By itself, calling PQgetResult will still cause the client to block
 194    until the server completes the next SQL command. This can be avoided by
 195    proper use of two more functions:
 196
 197    PQconsumeInput #
 198           If input is available from the server, consume it.
 199
 200 int PQconsumeInput(PGconn *conn);
 201
 202           PQconsumeInput normally returns 1 indicating “no error”, but
 203           returns 0 if there was some kind of trouble (in which case
 204           PQerrorMessage can be consulted). Note that the result does not
 205           say whether any input data was actually collected. After calling
 206           PQconsumeInput , the application can check PQisBusy and/or
 207           PQnotifies to see if their state has changed.
 208
 209           PQconsumeInput can be called even if the application is not
 210           prepared to deal with a result or notification just yet. The
 211           function will read available data and save it in a buffer,
 212           thereby causing a select() read-ready indication to go away. The
 213           application can thus use PQconsumeInput to clear the select()
 214           condition immediately, and then examine the results at leisure.
 215
 216    PQisBusy #
 217           Returns 1 if a command is busy, that is, PQgetResult would block
 218           waiting for input. A 0 return indicates that PQgetResult can be
 219           called with assurance of not blocking.
 220
 221 int PQisBusy(PGconn *conn);
 222
 223           PQisBusy will not itself attempt to read data from the server;
 224           therefore PQconsumeInput must be invoked first, or the busy
 225           state will never end.
 226
 227    A typical application using these functions will have a main loop that
 228    uses select() or poll() to wait for all the conditions that it must
 229    respond to. One of the conditions will be input available from the
 230    server, which in terms of select() means readable data on the file
 231    descriptor identified by PQsocket. When the main loop detects input
 232    ready, it should call PQconsumeInput to read the input. It can then
 233    call PQisBusy, followed by PQgetResult if PQisBusy returns false (0).
 234    It can also call PQnotifies to detect NOTIFY messages (see
 235    Section 32.9).
 236
 237    A client that uses PQsendQuery/PQgetResult can also attempt to cancel a
 238    command that is still being processed by the server; see Section 32.7.
 239    But regardless of the return value of PQcancelBlocking, the application
 240    must continue with the normal result-reading sequence using
 241    PQgetResult. A successful cancellation will simply cause the command to
 242    terminate sooner than it would have otherwise.
 243
 244    By using the functions described above, it is possible to avoid
 245    blocking while waiting for input from the database server. However, it
 246    is still possible that the application will block waiting to send
 247    output to the server. This is relatively uncommon but can happen if
 248    very long SQL commands or data values are sent. (It is much more
 249    probable if the application sends data via COPY IN, however.) To
 250    prevent this possibility and achieve completely nonblocking database
 251    operation, the following additional functions can be used.
 252
 253    PQsetnonblocking #
 254           Sets the nonblocking status of the connection.
 255
 256 int PQsetnonblocking(PGconn *conn, int arg);
 257
 258           Sets the state of the connection to nonblocking if arg is 1, or
 259           blocking if arg is 0. Returns 0 if OK, -1 if error.
 260
 261           In the nonblocking state, successful calls to PQsendQuery,
 262           PQputline, PQputnbytes, PQputCopyData, and PQendcopy will not
 263           block; their changes are stored in the local output buffer until
 264           they are flushed. Unsuccessful calls will return an error and
 265           must be retried.
 266
 267           Note that PQexec does not honor nonblocking mode; if it is
 268           called, it will act in blocking fashion anyway.
 269
 270    PQisnonblocking #
 271           Returns the blocking status of the database connection.
 272
 273 int PQisnonblocking(const PGconn *conn);
 274
 275           Returns 1 if the connection is set to nonblocking mode and 0 if
 276           blocking.
 277
 278    PQflush #
 279           Attempts to flush any queued output data to the server. Returns
 280           0 if successful (or if the send queue is empty), -1 if it failed
 281           for some reason, or 1 if it was unable to send all the data in
 282           the send queue yet (this case can only occur if the connection
 283           is nonblocking).
 284
 285 int PQflush(PGconn *conn);
 286
 287    After sending any command or data on a nonblocking connection, call
 288    PQflush. If it returns 1, wait for the socket to become read- or
 289    write-ready. If it becomes write-ready, call PQflush again. If it
 290    becomes read-ready, call PQconsumeInput , then call PQflush again.
 291    Repeat until PQflush returns 0. (It is necessary to check for
 292    read-ready and drain the input with PQconsumeInput , because the server
 293    can block trying to send us data, e.g., NOTICE messages, and won't read
 294    our data until we read its.) Once PQflush returns 0, wait for the
 295    socket to be read-ready and then read the response as described above.