客户端应用程序可以使用本节介绍的函数,请求取消服务器仍在处理的命令。
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可以安全地从信号处理程序中调用。对于PQcancel而言,PGcancel对象是只读的,因此也可以从与操作PGconn对象的线程不同的线程中调用。
PQrequestCancel #PQrequestCancel是以下函数的已弃用变体:PQcancel。
int PQrequestCancel(PGconn *conn);
请求服务器放弃当前命令的处理。它直接作用于PGconn对象,失败时会把错误消息存储到PGconn对象中(可通过PQerrorMessage获取)。虽然功能相同,但这种方法在多线程程序或信号处理程序中并不安全,因为它可能覆盖PGconn中的错误消息,从而破坏当前连接上正在进行的操作。