准备一个连接，以便通过该连接发送取消请求。

PGcancelConn *PQcancelCreate(PGconn *conn);

PQcancelCreate 会创建一个 PGcancelConn 对象，但它不会立即通过该连接发送取消请求。可以使用 PQcancelBlocking 以阻塞方式，或使用 PQcancelStart 以非阻塞方式，通过该连接发送取消请求。返回值可以传递给 PQcancelStatus 以检查 PGcancelConn 对象是否已成功创建。 PGcancelConn 对象是一个不应被应用程序直接访问的不透明结构。此 PGcancelConn 对象可用于以线程安全的方式取消原始连接上正在运行的查询。

在为取消请求设置连接时，将重用原始客户端的许多连接参数。重要的是，如果原始连接需要加密连接和/或目标主机验证（使用 sslmode 或 gssencmode），那么取消请求的连接将使用相同的要求进行建立。然而，在身份验证期间或身份验证客户端之后使用的任何连接选项都将被忽略，因为取消请求不需要身份验证，并且在提交取消请求后立即关闭连接。

请注意，当 PQcancelCreate 返回一个非空指针时，在完成使用后必须调用 PQcancelFinish 来释放结构和任何关联的内存块。即使取消请求失败或被放弃，也必须这样做。

以阻塞方式请求服务器放弃处理当前命令。

int PQcancelBlocking(PGcancelConn *cancelConn);

请求是通过提供的 PGcancelConn 发起的，该 PGcancelConn 需要使用 PQcancelCreate 创建。 PQcancelBlocking 的返回值是 1（如果取消请求已成功分派）或 0（如果未成功）。如果未成功，可以使用 PQcancelErrorMessage 检索错误消息。

成功分派取消请求并不保证该请求一定有效。如果取消有效，正在取消的命令将提前终止并返回错误结果。如果取消失败（例如，因为服务器已完成处理命令），则不会有任何可见的结果。

以非阻塞方式请求服务器放弃处理当前命令。

int PQcancelStart(PGcancelConn *cancelConn);

PostgresPollingStatusType PQcancelPoll(PGcancelConn *cancelConn);

请求是通过提供的 PGcancelConn 发起的，该 PGcancelConn 需要使用 PQcancelCreate 创建。 PQcancelStart 的返回值是 1（如果取消请求可以启动）或 0（如果不能）。如果未成功，可以使用 PQcancelErrorMessage 检索错误消息。

如果 PQcancelStart 成功，下一步就是轮询 libpq，以便它能够继续执行取消连接序列。使用 PQcancelSocket 获取数据库连接底层套接字的文件描述符。（警告：不要假设套接字在 PQcancelPoll 调用之间保持不变。）循环如下：如果 PQcancelPoll(cancelConn) 最后返回 PGRES_POLLING_READING，则等待套接字可读（由 select()、poll() 或类似的系统函数指示）。然后再次调用 PQcancelPoll(cancelConn)。反之，如果 PQcancelPoll(cancelConn) 最后返回 PGRES_POLLING_WRITING，则等待套接字可写，然后再次调用 PQcancelPoll(cancelConn)。在第一次迭代时，即如果您尚未调用 PQcancelPoll(cancelConn)，则表现得好像它最后返回了 PGRES_POLLING_WRITING。继续此循环，直到 PQcancelPoll(cancelConn) 返回 PGRES_POLLING_FAILED，指示连接过程失败，或 PGRES_POLLING_OK，指示取消请求已成功分派。

成功分派取消请求并不保证该请求一定有效。如果取消有效，正在取消的命令将提前终止并返回错误结果。如果取消失败（例如，因为服务器已完成处理命令），则不会有任何可见的结果。

在连接的任何时候，都可以通过调用 PQcancelStatus 来检查连接的状态。如果此调用返回 CONNECTION_BAD，则取消过程已失败；如果调用返回 CONNECTION_OK，则取消请求已成功分派。这两种状态都可以从 PQcancelPoll 的返回值中检测到，如上所述。在异步连接过程中（且仅在此过程中），也可能发生其他状态。这些状态指示连接过程的当前阶段，并且可能有助于向用户提供反馈。这些状态是：

请注意，尽管这些常量会保留（为了保持兼容性），但应用程序不应依赖于它们以特定顺序出现，或根本不出现，也不应依赖于状态始终是这些已记录值之一。应用程序可以执行类似如下操作：

switch(PQcancelStatus(conn))
{
        case CONNECTION_STARTED:
            feedback = "Connecting...";
            break;

        case CONNECTION_MADE:
            feedback = "Connected to server...";
            break;
.
.
.
        default:
            feedback = "Connecting...";
}

在 PQcancelPoll 的使用中，connect_timeout 连接参数被忽略；应用程序有责任决定是否已超过可接受的时间。否则，PQcancelStart 后跟 PQcancelPoll 循环等同于 PQcancelBlocking。

返回取消连接的状态。

ConnStatusType PQcancelStatus(const PGcancelConn *cancelConn);

状态可以是多个值之一。但是，在异步取消过程之外只能看到三个值：CONNECTION_ALLOCATED、CONNECTION_OK 和 CONNECTION_BAD。使用 PQcancelCreate 成功创建的 PGcancelConn 的初始状态是 CONNECTION_ALLOCATED。成功分派的取消请求的状态为 CONNECTION_OK。取消尝试失败由状态 CONNECTION_BAD 信号。OK 状态将一直保持，直到调用 PQcancelFinish 或 PQcancelReset。

有关其他可能返回的状态代码，请参阅 PQcancelStart 的条目。

成功分派取消请求并不保证该请求一定有效。如果取消有效，正在取消的命令将提前终止并返回错误结果。如果取消失败（例如，因为服务器已完成处理命令），则不会有任何可见的结果。

获取到服务器的取消连接套接字的文件描述符编号。

int PQcancelSocket(const PGcancelConn *cancelConn);

有效的描述符将大于或等于 0；结果 -1 表示当前没有打开服务器连接。这可能会因为在本节的任何函数（除了 PQcancelErrorMessage 和 PQcancelSocket 本身）的调用而改变。

返回最近由取消连接操作生成的错误消息。

char *PQcancelErrorMessage(const PGcancelConn *cancelconn);

几乎所有采用 PGcancelConn 的 libpq 函数，如果失败，都会为 PQcancelErrorMessage 设置消息。请注意，按照 libpq 的惯例，非空的 PQcancelErrorMessage 结果可能包含多行，并且会包含一个尾随的换行符。调用者不应直接释放结果。当关联的 PGcancelConn 句柄传递给 PQcancelFinish 时，它将被释放。不应期望结果字符串在 PGcancelConn 结构的操作之间保持不变。

关闭取消连接（如果尚未完成发送取消请求）。还释放 PGcancelConn 对象使用的内存。

void PQcancelFinish(PGcancelConn *cancelConn);

请注意，即使取消尝试失败（如 PQcancelStatus 所指示），应用程序也应调用 PQcancelFinish 来释放 PGcancelConn 对象使用的内存。调用 PQcancelFinish 后，不得再次使用 PGcancelConn 指针。

重置 PGcancelConn，以便可以重复使用它来建立新的取消连接。

void PQcancelReset(PGcancelConn *cancelConn);

如果 PGcancelConn 当前正用于发送取消请求，则该连接将被关闭。然后它将准备 PGcancelConn 对象，以便用于发送新的取消请求。

这可以用于为 PGconn 创建一个 PGcancelConn，并在原始 PGconn 的整个生命周期内重复使用它。

创建一个数据结构，其中包含使用 PQcancel 取消命令所需的信息。

PGcancel *PQgetCancel(PGconn *conn);

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

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

void PQfreeCancel(PGcancel *cancel);

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

PQcancel 是 PQcancelBlocking 的已弃用且不安全的变体，但可以安全地从信号处理程序中调用。

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

PQcancel 的存在仅出于向后兼容性原因。应使用 PQcancelBlocking 代替。 PQcancel 唯一的优点是如果 errbuf 是信号处理程序中的局部变量，则可以安全地从信号处理程序调用它。然而，这通常不被认为是一个足够大的优点，不值得冒此函数的安全风险。

对于 PQcancel 而言，PGcancel 对象是只读的，因此也可以从与操作 PGconn 对象不同的线程调用它。

PQcancel 的返回值是 1（如果取消请求已成功分派）或 0（如果未成功）。如果未成功，errbuf 将填充一个解释性错误消息。errbuf 必须是大小为 errbufsize 的字符数组（建议大小为 256 字节）。

PQrequestCancel 是 PQcancelBlocking 的已弃用且不安全的变体。

int PQrequestCancel(PGconn *conn);

PQrequestCancel 的存在仅出于向后兼容性原因。应使用 PQcancelBlocking 代替。使用 PQrequestCancel 而不是 PQcancelBlocking 没有好处。

请求服务器放弃处理当前命令。它直接作用于 PGconn 对象，并在失败时将错误消息存储在 PGconn 对象中（可以从中通过 PQerrorMessage 检索）。尽管功能相同，但这种方法在多线程程序或信号处理程序中并不安全，因为覆盖 PGconn 的错误消息可能会干扰正在进行的连接操作。