From 44e8a968e33f04974edc8ac9f184d009b036bbb7 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Sat, 30 Oct 2004 23:11:27 +0000 Subject: Invent a new, more thread-safe version of PQrequestCancel, called PQcancel. Use this new function in psql. Implement query cancellation in psql for Windows. Code by Magnus Hagander, documentation and minor editorialization by Tom Lane. --- doc/src/sgml/libpq.sgml | 184 +++++++++++++++++++++++++++++++++++------------- 1 file changed, 135 insertions(+), 49 deletions(-) (limited to 'doc/src') diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index d0c59424fc9..3b58108be11 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -1,5 +1,5 @@ @@ -2569,49 +2569,11 @@ if PQisBusy returns false (0). It can also call A client that uses PQsendQuery/PQgetResult can also attempt to cancel a command that is still being processed by the -server.cancelingSQL command - - - -PQrequestCancelPQrequestCancel - - - Requests that the server abandon - processing of the current command. - -int PQrequestCancel(PGconn *conn); - - - - -The return value is 1 if the cancel request was successfully -dispatched and 0 if not. (If not, PQerrorMessage tells why not.) -Successful dispatch is no guarantee that the request will have any -effect, however. Regardless of the return value of PQrequestCancel, -the application must continue with the normal result-reading -sequence using PQgetResult. If the cancellation -is effective, the current command will terminate early and return -an error result. If the cancellation fails (say, because the -server was already done processing the command), then there will -be no visible result at all. - - - -Note that if the current command is part of a transaction block, cancellation -will abort the whole transaction. - - - -PQrequestCancel can safely be invoked from a signal handler. -So, it is also possible to use it in conjunction with plain -PQexec, if the decision to cancel can be made in a signal -handler. For example, psql invokes -PQrequestCancel from a SIGINT signal handler, thus allowing -interactive cancellation of commands that it issues through PQexec. - - - - +server; see . But regardless of the return value +of PQcancel, the application must continue with the +normal result-reading sequence using PQgetResult. +A successful cancellation will simply cause the command to terminate +sooner than it would have otherwise. @@ -2699,6 +2661,125 @@ and then read the response as described above. + +Cancelling Queries in Progress + +cancelingSQL command + + +A client application can request cancellation of +a command that is still being processed by the +server, using the functions described in this section. + + + +PQgetCancelPQgetCancel + + + Creates a data structure containing the information needed to cancel + a command issued through a particular database connection. + +PGcancel *PQgetCancel(PGconn *conn); + + + + +PQgetCancel creates a +PGcancelPGcancel object given +a PGconn connection object. It will return NULL if the +given conn is NULL or an invalid connection. The +PGcancel object is an opaque structure that is not meant +to be accessed directly by the application; it can only be passed to +PQcancel or PQfreeCancel. + + + + + +PQfreeCancelPQfreeCancel + + + Frees a data structure created by PQgetCancel. + +void PQfreeCancel(PGcancel *cancel); + + + + +PQfreeCancel frees a data object previously created +by PQgetCancel. + + + + + +PQcancelPQcancel + + + Requests that the server abandon + processing of the current command. + +int PQcancel(PGcancel *cancel, char *errbuf, int errbufsize); + + + + +The return value is 1 if the cancel request was successfully +dispatched and 0 if not. If not, errbuf is filled with an error +message explaining why not. errbuf must be a char array of size +errbufsize (the recommended size is 256 bytes). + + + +Successful dispatch is no guarantee that the request will have any effect, +however. If the cancellation is effective, the current command will terminate +early and return an error result. If the cancellation fails (say, because the +server was already done processing the command), then there will be no visible +result at all. + + + +PQcancel can safely be invoked from a signal handler, +if the errbuf is a local variable in the signal handler. The +PGcancel object is read-only as far as +PQcancel is concerned, so it can also be invoked from a +thread that is separate from the one manipulating the PGconn +object. + + + + + + + +PQrequestCancelPQrequestCancel + + + Requests that the server abandon + processing of the current command. + +int PQrequestCancel(PGconn *conn); + + + + +PQrequestCancel is a deprecated variant of +PQcancel. It operates directly on the +PGconn object, and in case of failure stores the +error message in the PGconn object (whence it can be +retrieved by PQerrorMessage). Although the +functionality is the same, this approach creates hazards for multiple-thread +programs and signal handlers, since it is possible that overwriting the +PGconn's error message will mess up the operation currently +in progress on the connection. + + + + + + + + The Fast-Path Interface @@ -3852,11 +3933,16 @@ passed around freely between threads. -The deprecated functions PQoidStatus and -fe_setauthsvc are not thread-safe and should not be -used in multithread programs. PQoidStatus can be -replaced by PQoidValue. There is no good reason to -call fe_setauthsvc at all. +The deprecated functions +PQrequestCancel, +PQoidStatus and +fe_setauthsvc +are not thread-safe and should not be used in multithread programs. +PQrequestCancel can be replaced by +PQcancel. +PQoidStatus can be replaced by +PQoidValue. +There is no good reason to call fe_setauthsvc at all. -- cgit v1.2.3