33.6. 取消进行中的查询

Client 端应用程序可以使用本节中描述的功能来请求取消服务器仍在处理的命令。

• 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 *的 char 数组(建议大小为 256 个字节)。

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

如果* errbuf *是 signal 处理程序中的局部变量，则可以安全地从 signal 处理程序中调用PQcancel。就PQcancel而言，PGcancel对象是只读的，因此也可以从与处理PGconn对象的线程分开的线程中调用它。

• PQrequestCancel
  • PQrequestCancel是PQcancel弃用的变体。

int PQrequestCancel(PGconn *conn);

请求服务器放弃当前命令的处理。它直接在PGconn对象上运行，并且在发生故障的情况下，将错误消息存储在PGconn对象中(因此可以通过PQerrorMessage进行检索)。尽管功能相同，但是这种方法会给多线程程序和 signal 处理程序带来危险，因为覆盖PGconn的错误消息可能会使当前正在进行的连接操作混乱。