---

4.3 Asynchronous Retrieval

Sometimes you don’t want to wait idly for pg-exec to complete — for example, the query is complicated and/or the results are large — instead preferring to do some other computation in the meantime. In these cases, you can interact with the database asynchronously, that is, you register a query at one time, and check for its completion at a later time. In between, you can collect partial results and notifications, or decide to cancel the query altogether.

See Parameters, for background info on pg-send-query-params and pg-send-query-prepared.

Procedure: pg-send-query conn query ¶

Send conn a non-blocking query (string). Return #t iff successful. If not successful, error message is retrievable with pg-error-message.

Procedure: pg-send-query-params conn query parms ¶

Like pg-send-query, except that query is a parameterized string, and parms is a parameter-vector.

Procedure: pg-send-query-prepared conn stname parms ¶

Like pg-exec-prepared, except asynchronous. Also, return #t if successful.

Procedure: pg-get-result conn ¶

Return a result from conn, or #f.

Procedure: pg-consume-input conn ¶

Consume input from conn. Return #t iff successful.

Procedure: pg-is-busy? conn ¶

Return #t if there is data waiting for pg-consume-input, otherwise #f.

Procedure: pg-request-cancel conn ¶

Request a cancellation on conn. Return #t iff the cancel request was successfully dispatched. If not, pg-error-message tells why not. Successful dispatch is no guarantee that the request will have any effect, however. Regardless of the return value, the client must continue with the normal result-reading sequence using pg-get-result. If the cancellation is effective, the current query will terminate early and return an error result. If the cancellation fails (say, because the backend was already done processing the query), then there will be no visible result at all.

Note that if the current query is part of a transaction, cancellation will abort the whole transaction.

Procedure: pg-flush conn ¶

Flush output for connection conn. Return zero if successful (or if the send queue is empty); -1 if flushing failed for some reason; or one if not all data was sent (only possible for a non-blocking connection).