pg_result_callback

pg_result_callback
Prev	4.4. Asynchronous Query Processing Commands	Next

pg_result_callback — Set a callback for asynchronous SQL command result availability

Synopsis

pg_result_callback conn ?callbackCommand?

Description

pg_result_callback creates, changes, or cancels a request to execute a callback command when the result of an asynchronous query is ready. With a callbackCommand parameter, the callback command is established or an existing callback command is replaced. With no callbackCommand parameter, any existing callback command is canceled.

To use event-driven asynchronous queries, first establish a callback command with pg_result_callback, then issue a command with pg_sendquery, pg_sendquery_prepared, or pg_sendquery_params. The Tcl/Tk application can then continue processing while the query is executing, without blocking or busy-waiting for the result. For example, a Tk application can continue to respond to user-interface events. Or, a Tcl application can simultaneously wait for a query result or a network socket input ready condition. When the query result is available, the Tcl/Tk event system will execute the callback command.

The callback command string is executed from the Tcl idle loop. That is the normal idle state of an application written with Tk. In non-Tk Tcl shells, you can execute update or vwait to cause the idle loop to be entered.

Arguments

conn: The handle of the connection on which to establish the callback.
callbackCommand: If present, provides the command string to execute when an asynchronous query result is ready. If absent, an existing asynchronous query result callback command is canceled.

Return Value

Nothing. Throws a Tcl error if an error occurs.

Notes

An established callback command will be automatically removed when any of the following occurs:

The callbackCommand executes because a result is ready.
pg_getresult is called, which blocks until a result is ready.
pg_cancelrequest is called, canceling the asynchronous query.
The connection to the PostgreSQL server is closed.
pg_result_callback is called - without a callbackCommand, to remove the callback, or with a new callbackCommand to replace the existing callback.

While an asynchronous query callback command is in place, synchronous query commands (pg_exec, pg_select, etc.) are not allowed and will throw a Tcl error.

This command was added in pgtclng-1.6.0. It is not available in pgintcl. This feature was suggested by Kyle Bateman (kyleb), with the initial implementation designed and written by Miguel Sofer (msofer).

See Section 5.12, “Example - Asynchronous Query with Event-Driven Results” for an example.

Prev	Up	Next
pg_blocking	Home	4.5. Notification and Notice Processing Commands