61.2.4 Asynchronous Interface Functions

Making command by command examples is too complex with the asynchronous interface functions. See the examples section for complete calling sequences.

Function: pq-connect-start conninfo

Begin establishing an asynchronous database connection. conninfo A string containing the connection options. See the documentation of pq-connectdb for a listing of all the available flags.

Function: pq-connect-poll conn

An intermediate function to be called during an asynchronous database connection. conn A database connection object. The result codes are documented in a previous section.

Function: pq-is-busy conn

Returns t if pq-get-result would block waiting for input. conn A database connection object.

Function: pq-consume-input conn

Consume any available input from the backend. conn A database connection object.

Nil is returned if anything bad happens.

Function: pq-reset-start conn

Reset connection to the backend asynchronously. conn A database connection object.

Function: pq-reset-poll conn

Poll an asynchronous reset for completion conn A database connection object.

Function: pq-reset-cancel conn

Attempt to request cancellation of the current operation. conn A database connection object.

The return value is t if the cancel request was successfully dispatched, nil if not (in which case conn->errorMessage is set). Note: successful dispatch is no guarantee that there will be any effect at the backend. The application must read the operation result as usual.

Function: pq-send-query conn query

Submit a query to Postgres and don’t wait for the result. conn A database connection object. Returns: t if successfully submitted nil if error (conn->errorMessage is set)

Function: pq-get-result conn

Retrieve an asynchronous result from a query. conn A database connection object.

nil is returned when no more query work remains.

Function: pq-set-nonblocking conn arg

Sets the PGconn’s database connection non-blocking if the arg is TRUE or makes it non-blocking if the arg is FALSE, this will not protect you from PQexec(), you’ll only be safe when using the non-blocking API. conn A database connection object.

Function: pq-is-nonblocking conn

Return the blocking status of the database connection conn A database connection object.

Function: pq-flush conn

Force the write buffer to be written (or at least try) conn A database connection object.

Function: PQsetenvStart conn

Start asynchronously passing environment variables to a backend. conn A database connection object.

Compatibility note: this function is only available with libpq-7.0.

Function: PQsetenvPoll conn

Check an asynchronous environment variables transfer for completion. conn A database connection object.

Compatibility note: this function is only available with libpq-7.0.

Function: PQsetenvAbort conn

Attempt to terminate an asynchronous environment variables transfer. conn A database connection object.

Compatibility note: this function is only available with libpq-7.0.