34.7. 取消正在进行的查询#

客户端应用程序可以使用本节中描述的函数请求取消服务器仍在处理的命令。

PQgetCancel #

创建一个数据结构，其中包含通过特定数据库连接发出的命令取消所需的信息。

PGcancel *PQgetCancel(PGconn *conn);

PQgetCancel 给定一个 PGconn 连接对象，创建一个 PGcancel 对象。如果给定的 conn 为 NULL 或无效连接，它将返回 NULL。 PGcancel 对象是一个不透明结构，不打算由应用程序直接访问；它只能传递给 PQcancel 或 PQfreeCancel。

PQfreeCancel #

释放由 PQgetCancel 创建的数据结构。

void PQfreeCancel(PGcancel *cancel);

PQfreeCancel 释放先前由 PQgetCancel 创建的数据对象。

PQcancel #

请求服务器放弃处理当前命令。

int PQcancel(PGcancel *cancel, char *errbuf, int errbufsize);

如果取消请求已成功发送，则返回值为 1，否则为 0。如果没有成功，则 errbuf 会填充说明性错误消息。 errbuf 必须是一个大小为 errbufsize 的字符数组（建议大小为 256 字节）。

但是，成功发送并不保证请求会产生任何效果。如果取消有效，则当前命令将提前终止并返回错误结果。如果取消失败（例如，因为服务器已经处理完命令），那么根本不会有可见的结果。

如果 errbuf 是信号处理程序中的局部变量，则可以安全地从信号处理程序调用 PQcancel。 PGcancel 对象对于 PQcancel 来说是只读的，因此它也可以从与操作 PGconn 对象不同的线程调用。

PQrequestCancel #

PQrequestCancel 是 PQcancel 的弃用变体。

int PQrequestCancel(PGconn *conn);

请求服务器放弃处理当前命令。它直接在 PGconn 对象上操作，并且在失败的情况下将错误消息存储在 PGconn 对象中（可通过 PQerrorMessage 检索）。虽然功能相同，但此方法在多线程程序或信号处理程序中不安全，因为覆盖 PGconn 的错误消息可能会搞乱当前正在连接上进行的操作。