diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index d829a4b..4e0431e 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -3947,9 +3947,14 @@ int PQsendQuery(PGconn *conn, const char *command);
After successfully calling PQsendQuery, call
PQgetResult one or more times to obtain the
- results. PQsendQuery cannot be called again
- (on the same connection) until PQgetResult
- has returned a null pointer, indicating that the command is done.
+ results. If pipelining is enabled PQsendQuery
+ may be called multiple times before reading the results. See
+ PQsetPipelining and PQisPipelining.
+ Call PQgetSentQuery to get a PGquery
+ which can be used to identify which results obtained from
+ PQgetResult belong to each pipelined query.
+ If only one query is dispatched at a time, you can call PQgetResult
+ until a NULL value is returned to indicate the end of the query.
@@ -4133,8 +4138,8 @@ PGresult *PQgetResult(PGconn *conn);
PQgetResult must be called repeatedly until
- it returns a null pointer, indicating that the command is done.
- (If called when no command is active,
+ it returns a null pointer, indicating that all dispatched commands
+ are done. (If called when no command is active,
PQgetResult will just return a null pointer
at once.) Each non-null result from
PQgetResult should be processed using the
@@ -4144,14 +4149,17 @@ PGresult *PQgetResult(PGconn *conn);
PQgetResult will block only if a command is
active and the necessary response data has not yet been read by
PQconsumeInput.
+ If query pipelining is being used, PQgetResultQuery
+ can be called after PQgetResult to match the result to the query.
Even when PQresultStatus indicates a fatal
- error, PQgetResult should be called until it
- returns a null pointer, to allow libpq to
- process the error information completely.
+ error, PQgetResult should be called until the
+ query has no more results (null pointer return if not using query
+ pipelining, otherwise see PQgetResultQuery),
+ to allow libpq to process the error information completely.
@@ -4385,6 +4393,158 @@ int PQflush(PGconn *conn);
read-ready and then read the response as described above.
+
+
+
+ PQsetPipelining
+
+ PQsetPipelining
+
+
+
+
+
+ Enables or disables query pipelining.
+
+int PQsetPipelining(PGconn *conn, int arg);
+
+
+
+
+ Enables pipelining for the connectino if arg is 1, or disables it
+ if arg is 0. When pipelining is enabled multiple async queries can
+ be sent before processing the results of the first. If pipelining
+ is disabled an error will be raised an async query is attempted
+ while another is active.
+
+
+
+
+
+
+ PQisPipelining
+
+ PQisPipelining
+
+
+
+
+
+ Returns the pipelining status of the connection
+
+int PQisPipelining(PGconn *conn);
+
+
+
+
+ Returns 1 if pipelining is enabled, or 0 if pipeling is disabled.
+ Query pipelining is disabled unless enabled with a call to
+ PQsetPipelining.
+
+
+
+
+
+
+ PQgetQueryCommand
+
+ PQgetQueryCommand
+
+
+
+
+
+ Returns the query string associated with the PGquery.
+
+const char * PQgetQueryCommand(PGquery *query);
+
+
+
+
+ When using query pipelining this function can be used to retrieve the command
+ that created the query object.
+
+
+
+
+
+
+ PQgetResultQuery
+
+ PQgetResultQuery
+
+
+
+
+
+ Returns the first async query to recieve results, or NULL if no
+ async queries are active.
+
+PGquery * PQgetResultQuery(PGconn *conn);
+
+
+
+
+ When pipelining queries this function indicates which query the
+ result of PQgetResult results from.
+ Call this function immediately after calling
+ PQgetResult, or immediately before if a result
+ is ready to read, indicated by PQisBusy
+ being false. The PGquery remains valid
+ until the next libpq call that consumes input.
+
+
+
+
+
+
+ PQgetNextQuery
+
+ PQgetNextQuery
+
+
+
+
+
+ Returns the next PGquery in the list of
+ pipelined queries.
+
+PGquery * PQgetNextQuery(PGquery *query);
+
+
+
+
+ This function can be used to iterate each pending async query,
+ starting with PQgetResultQuery
+ and ending with PQgetSentQuery.
+
+
+
+
+
+ PQgetSentQuery
+
+ PQgetSentQuery
+
+
+
+
+
+ Returns the last PGquery in the list of
+ dispatched async queries waiting for results.
+
+PGquery * PQgetSentQuery(PGquery *query);
+
+
+
+
+ Call this function after dispatching an async query to get
+ a PGquery that can be used to identify
+ the originating query for each result obtained by
+ PGgetResult.
+
+
+
@@ -4411,7 +4571,7 @@ int PQflush(PGconn *conn);
immediately after a successful call of PQsendQuery
(or a sibling function). This mode selection is effective only for the
currently executing query. Then call PQgetResult
- repeatedly, until it returns null, as documented in . If the query returns any rows, they are returned
as individual PGresult objects, which look like
normal query results except for having status code
@@ -4420,8 +4580,8 @@ int PQflush(PGconn *conn);
the query returns zero rows, a zero-row object with status
PGRES_TUPLES_OK is returned; this is the signal that no
more rows will arrive. (But note that it is still necessary to continue
- calling PQgetResult until it returns null.) All of
- these PGresult objects will contain the same row
+ calling PQgetResult until the last query result is returned.)
+ All of these PGresult objects will contain the same row
description data (column names, types, etc) that an ordinary
PGresult object for the query would have.
Each object should be freed with PQclear as usual.