PQcancelCreate
#准备一个连接,以便通过该连接发送取消请求。
PGcancelConn *PQcancelCreate(PGconn *conn);
PQcancelCreate
会创建一个 PGcancelConn
对象,但它不会立即通过该连接发送取消请求。可以使用 PQcancelBlocking
以阻塞方式,或使用 PQcancelStart
以非阻塞方式,通过该连接发送取消请求。返回值可以传递给 PQcancelStatus
以检查 PGcancelConn
对象是否已成功创建。 PGcancelConn
对象是一个不应被应用程序直接访问的不透明结构。此 PGcancelConn
对象可用于以线程安全的方式取消原始连接上正在运行的查询。
在为取消请求设置连接时,将重用原始客户端的许多连接参数。重要的是,如果原始连接需要加密连接和/或目标主机验证(使用 sslmode
或 gssencmode
),那么取消请求的连接将使用相同的要求进行建立。然而,在身份验证期间或身份验证客户端之后使用的任何连接选项都将被忽略,因为取消请求不需要身份验证,并且在提交取消请求后立即关闭连接。
请注意,当 PQcancelCreate
返回一个非空指针时,在完成使用后必须调用 PQcancelFinish
来释放结构和任何关联的内存块。即使取消请求失败或被放弃,也必须这样做。
PQcancelBlocking
#以阻塞方式请求服务器放弃处理当前命令。
int PQcancelBlocking(PGcancelConn *cancelConn);
请求是通过提供的 PGcancelConn
发起的,该 PGcancelConn
需要使用 PQcancelCreate
创建。 PQcancelBlocking
的返回值是 1(如果取消请求已成功分派)或 0(如果未成功)。如果未成功,可以使用 PQcancelErrorMessage
检索错误消息。
成功分派取消请求并不保证该请求一定有效。如果取消有效,正在取消的命令将提前终止并返回错误结果。如果取消失败(例如,因为服务器已完成处理命令),则不会有任何可见的结果。
PQcancelStart
PQcancelPoll
#以非阻塞方式请求服务器放弃处理当前命令。
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
的返回值中检测到,如上所述。在异步连接过程中(且仅在此过程中),也可能发生其他状态。这些状态指示连接过程的当前阶段,并且可能有助于向用户提供反馈。这些状态是:
CONNECTION_ALLOCATED
#等待调用 PQcancelStart
或 PQcancelBlocking
来实际打开套接字。这是调用 PQcancelCreate
或 PQcancelReset
后的连接状态。此时尚未启动与服务器的任何连接。要实际开始发送取消请求,请使用 PQcancelStart
或 PQcancelBlocking
。
CONNECTION_STARTED
#正在等待连接建立。
CONNECTION_MADE
#连接成功;正在等待发送。
CONNECTION_AWAITING_RESPONSE
#正在等待服务器响应。
CONNECTION_SSL_STARTUP
#正在协商 SSL 加密。
CONNECTION_GSS_STARTUP
#正在协商 GSS 加密。
请注意,尽管这些常量会保留(为了保持兼容性),但应用程序不应依赖于它们以特定顺序出现,或根本不出现,也不应依赖于状态始终是这些已记录值之一。应用程序可以执行类似如下操作:
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
。
PQcancelStatus
#返回取消连接的状态。
ConnStatusType PQcancelStatus(const PGcancelConn *cancelConn);
状态可以是多个值之一。但是,在异步取消过程之外只能看到三个值:CONNECTION_ALLOCATED
、CONNECTION_OK
和 CONNECTION_BAD
。使用 PQcancelCreate
成功创建的 PGcancelConn
的初始状态是 CONNECTION_ALLOCATED
。成功分派的取消请求的状态为 CONNECTION_OK
。取消尝试失败由状态 CONNECTION_BAD
信号。OK 状态将一直保持,直到调用 PQcancelFinish
或 PQcancelReset
。
有关其他可能返回的状态代码,请参阅 PQcancelStart
的条目。
成功分派取消请求并不保证该请求一定有效。如果取消有效,正在取消的命令将提前终止并返回错误结果。如果取消失败(例如,因为服务器已完成处理命令),则不会有任何可见的结果。
PQcancelSocket
#获取到服务器的取消连接套接字的文件描述符编号。
int PQcancelSocket(const PGcancelConn *cancelConn);
有效的描述符将大于或等于 0;结果 -1 表示当前没有打开服务器连接。这可能会因为在本节的任何函数(除了 PQcancelErrorMessage
和 PQcancelSocket
本身)的调用而改变。
PQcancelErrorMessage
#返回最近由取消连接操作生成的错误消息。
char *PQcancelErrorMessage(const PGcancelConn *cancelconn);
几乎所有采用 PGcancelConn
的 libpq 函数,如果失败,都会为 PQcancelErrorMessage
设置消息。请注意,按照 libpq 的惯例,非空的 PQcancelErrorMessage
结果可能包含多行,并且会包含一个尾随的换行符。调用者不应直接释放结果。当关联的 PGcancelConn
句柄传递给 PQcancelFinish
时,它将被释放。不应期望结果字符串在 PGcancelConn
结构的操作之间保持不变。
PQcancelFinish
#关闭取消连接(如果尚未完成发送取消请求)。还释放 PGcancelConn
对象使用的内存。
void PQcancelFinish(PGcancelConn *cancelConn);
请注意,即使取消尝试失败(如 PQcancelStatus
所指示),应用程序也应调用 PQcancelFinish
来释放 PGcancelConn
对象使用的内存。调用 PQcancelFinish
后,不得再次使用 PGcancelConn
指针。
PQcancelReset
#重置 PGcancelConn
,以便可以重复使用它来建立新的取消连接。
void PQcancelReset(PGcancelConn *cancelConn);
如果 PGcancelConn
当前正用于发送取消请求,则该连接将被关闭。然后它将准备 PGcancelConn
对象,以便用于发送新的取消请求。
这可以用于为 PGconn
创建一个 PGcancelConn
,并在原始 PGconn
的整个生命周期内重复使用它。
这些函数代表发送取消请求的旧方法。尽管它们仍然有效,但由于它们不会以加密方式发送取消请求(即使原始连接指定了 sslmode
或 gssencmode
来要求加密),因此已被弃用。因此,强烈不建议在新代码中使用这些旧方法,并建议将现有代码更改为使用新函数。
PQgetCancel
#创建一个数据结构,其中包含使用 PQcancel
取消命令所需的信息。
PGcancel *PQgetCancel(PGconn *conn);
PQgetCancel
使用 PGconn
连接对象创建一个 PGcancel
对象。如果提供的 conn
是 NULL
或无效连接,它将返回 NULL
。 PGcancel
对象是一个不应由应用程序直接访问的不透明结构;它只能传递给 PQcancel
或 PQfreeCancel
。
PQfreeCancel
#释放由 PQgetCancel
创建的数据结构。
void PQfreeCancel(PGcancel *cancel);
PQfreeCancel
释放之前由 PQgetCancel
创建的数据对象。
PQcancel
#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
#PQrequestCancel
是 PQcancelBlocking
的已弃用且不安全的变体。
int PQrequestCancel(PGconn *conn);
PQrequestCancel
的存在仅出于向后兼容性原因。应使用 PQcancelBlocking
代替。使用 PQrequestCancel
而不是 PQcancelBlocking
没有好处。
请求服务器放弃处理当前命令。它直接作用于 PGconn
对象,并在失败时将错误消息存储在 PGconn
对象中(可以从中通过 PQerrorMessage
检索)。尽管功能相同,但这种方法在多线程程序或信号处理程序中并不安全,因为覆盖 PGconn
的错误消息可能会干扰正在进行的连接操作。
如果您在文档中发现任何不正确、与您对特定功能的使用经验不符或需要进一步澄清的内容,请使用 此表格 报告文档问题。