database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-07-30 11:03:19 +03:00
Code Activity

Invent a new, more thread-safe version of PQrequestCancel, called PQcancel.

Browse Source 
Use this new function in psql.  Implement query cancellation in psql for
Windows.  Code by Magnus Hagander, documentation and minor editorialization
by Tom Lane.
This commit is contained in:
Tom Lane
2004-10-30 23:11:27 +00:00
parent 80559fa9e9
commit 44e8a968e3
8 changed files with 399 additions and 118 deletions
Download Patch File Download Diff File Expand all files Collapse all files

184
doc/src/sgml/libpq.sgml
View File

@ -1,5 +1,5 @@
<!--
$PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.166 2004/10/18 22:00:41 tgl Exp $
$PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.167 2004/10/30 23:09:59 tgl Exp $
-->
<chapter id="libpq">
@ -2569,49 +2569,11 @@ if <function>PQisBusy</function> returns false (0). It can also call
A client that uses
<function>PQsendQuery</function>/<function>PQgetResult</function> can
also attempt to cancel a command that is still being processed by the
server.<indexterm><primary>canceling</><secondary>SQL command</></>
<variablelist>
<varlistentry>
<term><function>PQrequestCancel</function><indexterm><primary>PQrequestCancel</></></term>
<listitem>
<para>
Requests that the server abandon
processing of the current command.
<synopsis>
int PQrequestCancel(PGconn *conn);
</synopsis>
</para>
<para>
The return value is 1 if the cancel request was successfully
dispatched and 0 if not. (If not, <function>PQerrorMessage</function> tells why not.)
Successful dispatch is no guarantee that the request will have any
effect, however. Regardless of the return value of <function>PQrequestCancel</function>,
the application must continue with the normal result-reading
sequence using <function>PQgetResult</function>. 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.
</para>
<para>
Note that if the current command is part of a transaction block, cancellation
will abort the whole transaction.
</para>
<para>
<function>PQrequestCancel</function> can safely be invoked from a signal handler.
So, it is also possible to use it in conjunction with plain
<function>PQexec</function>, if the decision to cancel can be made in a signal
handler. For example, <application>psql</application> invokes
<function>PQrequestCancel</function> from a <symbol>SIGINT</> signal handler, thus allowing
interactive cancellation of commands that it issues through <function>PQexec</function>.
</para>
</listitem>
</varlistentry>
</variablelist>
server; see <xref linkend="libpq-cancel">. But regardless of the return value
of <function>PQcancel</function>, the application must continue with the
normal result-reading sequence using <function>PQgetResult</function>.
A successful cancellation will simply cause the command to terminate
sooner than it would have otherwise.
</para>
<para>
@ -2699,6 +2661,125 @@ and then read the response as described above.
</sect1>
<sect1 id="libpq-cancel">
<title>Cancelling Queries in Progress</title>
<indexterm zone="libpq-cancel"><primary>canceling</><secondary>SQL command</></>
<para>
A client application can request cancellation of
a command that is still being processed by the
server, using the functions described in this section.
<variablelist>
<varlistentry>
<term><function>PQgetCancel</function><indexterm><primary>PQgetCancel</></></term>
<listitem>
<para>
Creates a data structure containing the information needed to cancel
a command issued through a particular database connection.
<synopsis>
PGcancel *PQgetCancel(PGconn *conn);
</synopsis>
</para>
<para>
<function>PQgetCancel</function> creates a
<structname>PGcancel</><indexterm><primary>PGcancel</></> object given
a <structname>PGconn</> connection object. It will return NULL if the
given <parameter>conn</> is NULL or an invalid connection. The
<structname>PGcancel</> object is an opaque structure that is not meant
to be accessed directly by the application; it can only be passed to
<function>PQcancel</function> or <function>PQfreeCancel</function>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><function>PQfreeCancel</function><indexterm><primary>PQfreeCancel</></></term>
<listitem>
<para>
Frees a data structure created by <function>PQgetCancel</function>.
<synopsis>
void PQfreeCancel(PGcancel *cancel);
</synopsis>
</para>
<para>
<function>PQfreeCancel</function> frees a data object previously created
by <function>PQgetCancel</function>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><function>PQcancel</function><indexterm><primary>PQcancel</></></term>
<listitem>
<para>
Requests that the server abandon
processing of the current command.
<synopsis>
int PQcancel(PGcancel *cancel, char *errbuf, int errbufsize);
</synopsis>
</para>
<para>
The return value is 1 if the cancel request was successfully
dispatched and 0 if not. If not, <parameter>errbuf</> is filled with an error
message explaining why not. <parameter>errbuf</> must be a char array of size
<parameter>errbufsize</> (the recommended size is 256 bytes).
</para>
<para>
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.
</para>
<para>
<function>PQcancel</function> can safely be invoked from a signal handler,
if the <parameter>errbuf</> is a local variable in the signal handler. The
<structname>PGcancel</> object is read-only as far as
<function>PQcancel</function> is concerned, so it can also be invoked from a
thread that is separate from the one manipulating the <structname>PGconn</>
object.
</para>
</listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
<term><function>PQrequestCancel</function><indexterm><primary>PQrequestCancel</></></term>
<listitem>
<para>
Requests that the server abandon
processing of the current command.
<synopsis>
int PQrequestCancel(PGconn *conn);
</synopsis>
</para>
<para>
<function>PQrequestCancel</function> is a deprecated variant of
<function>PQcancel</function>. It operates directly on the
<structname>PGconn</> object, and in case of failure stores the
error message in the <structname>PGconn</> object (whence it can be
retrieved by <function>PQerrorMessage</function>). Although the
functionality is the same, this approach creates hazards for multiple-thread
programs and signal handlers, since it is possible that overwriting the
<structname>PGconn</>'s error message will mess up the operation currently
in progress on the connection.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect1>
<sect1 id="libpq-fastpath">
<title>The Fast-Path Interface</title>
@ -3852,11 +3933,16 @@ passed around freely between threads.
</para>
<para>
The deprecated functions <function>PQoidStatus</function> and
<function>fe_setauthsvc</function> are not thread-safe and should not be
used in multithread programs. <function>PQoidStatus</function> can be
replaced by <function>PQoidValue</function>. There is no good reason to
call <function>fe_setauthsvc</function> at all.
The deprecated functions
<function>PQrequestCancel</function>,
<function>PQoidStatus</function> and
<function>fe_setauthsvc</function>
are not thread-safe and should not be used in multithread programs.
<function>PQrequestCancel</function> can be replaced by
<function>PQcancel</function>.
<function>PQoidStatus</function> can be replaced by
<function>PQoidValue</function>.
There is no good reason to call <function>fe_setauthsvc</function> at all.
</para>
<para>