27.4. 异步命令处理

PQexec 函数对普通的同步应用里提交命令已经是足够用的了。 但是它却有几个主要的缺陷,而这些缺陷可能对某些用户很重要:

不想受到这些限制的应用可以改用下面的函数,这些函数也是构造 PQexec 的函数: 也有 PQsendQueryParamsPQsendQueryPrepared, 他们可以和 PQgetResult 一起使用,分别用于复制 PQexecParamsPQexecPrepared 的功能。

PQsendQuery

向服务器提交一个命令而不等待结果。 如果查询成功发送则返回 1,否则返回 0。 (此时,可以用PQerrorMessage获取关于失败的信息)。

int PQsendQuery(PGconn *conn, const char *command);

在成功调用 PQsendQuery后,调用 PQgetResult 一次或者多次获取结果。 在 PQgetResult 返回 NULL 指针,表明命令完成之前, 我们不能再调用 PQsendQuery (在同一次连接里)。

PQsendQueryParams

给服务器提交一个命令和(命令需要的)分隔的参数,而不等待结果。

int PQsendQueryParams(PGconn *conn,
                      const char *command,
                      int nParams,
                      const Oid *paramTypes,
                      const char * const *paramValues,
                      const int *paramLengths,
                      const int *paramFormats,
                      int resultFormat);

这个等效于 PQsendQuery,只是查询参数可以和查询字串分开声明。 函数的参数处理和 PQexecParams 一样。和 PQexecParams 类似, 它不能在 2.0 版本的协议连接上工作,并且它只允许在查询字串里出现一条命令。

PQsendQueryPrepared

发送一个执行带有给出参数的准备好的语句的请求,不等待结果。

int PQsendQueryPrepared(PGconn *conn,
                        const char *stmtName,
                        int nParams,
                        const char * const *paramValues,
                        const int *paramLengths,
                        const int *paramFormats,
                        int resultFormat);

这个函数类似 PQsendQueryParams,但是要执行的命令是通过给一个前面准备好的语句命名来声明的, 而不是给出一个查询字串。函数的参数处理和 PQexecPrepared 一样。类似 PQexecPrepared, 它也不能在 2.0 版本的协议连接上跑。

PQgetResult

等待从前面 PQsendQueryPQsendQueryParams, 或者 PQsendQueryPrepared 调用返回的下一个结果, 然后返回之。当命令结束并且没有更多结果后返回 NULL。

PGresult *PQgetResult(PGconn *conn);

必须重复的调用 PQgetResult ,直到它返回 NULL, 表明该命令结束。(如果在没有活跃的命令时调用, PQgetResult 将只是立即返回一个空指针。) 每个 PQgetResult 返回的非 NULL 结果都应该用前面描述的 PGresult 访问函数进行分析。 不要忘了在结束分析后用 PQclear 释放每个结果对象。 注意,PQgetResult 只是在有一个命令是活跃的而且必须的返回数据还没有被 PQconsumeInput 读取时阻塞。

使用 PQsendQueryPQgetResult 解决了 PQexec的一个问题: 如果一个命令字符串包含多个 SQL 命令, 这些命令的结果可以独立的获得。(顺便说一句:这样就允许一种简单的重叠处理模式, 客户端可以处理一个命令的结果而服务器可以仍然在处理同一命令字符串的后面的查询。) 但是,调用 PQgetResult 将仍然导致前端被阻塞住直到服务器完成下一个 SQL 命令。这一点可以通过合理的使用下面两个函数来避免:

PQconsumeInput

如果存在服务器来的输入可用,则使用之。

int PQconsumeInput(PGconn *conn);

PQconsumeInput 通常返回 1 表明"没有错误", 而返回 0 表明有某种错误发生,(这个时候可以用PQerrorMessage)。 注意这个结果并不表明实际上是否收集了数据。在调用 PQconsumeInput之后,应用可以检查 PQisBusy 和/或 PQnotifies 看一眼它们的状态是否改变。

PQconsumeInput 可以在应用还没有做好处理结果或通知的情况下被调用。 这个函数将读取可用的数据并且在一个缓冲区里保存它,这样导致一个 select() 读准备好标识的生成。这样应用就可以使用 PQconsumeInput 立即清掉 select() 条件,然后在空闲的时候检查结果。

PQisBusy

在查询忙的时候返回 1 ,也就是说,PQgetResult 将阻塞住等待输入。 一个 0 的返回表明这时调用 PQgetResult等以确保不阻塞。

int PQisBusy(PGconn *conn);

PQisBusy 本身将不会试图从服务器读取数据;所以必须先调用 PQconsumeInput,否则忙状态将永远不会消除。

一个使用这些函数的典型的应用将有一个主循环使用 select() 等待所有它必须处理的条件。其中一个条件将会是服务器来的数据已准备好, 从 select() 的角度来看就是 PQsocket 标识的文件描述符上已经有可读取的数据。 当主循环侦测到输入准备好,它将调用PQconsumeInput读取输入。 然后可以调用 PQisBusy 返回 false (0)后面可以跟着 PQgetResult。同样它(用户应用)可以调用 PQnotifies检测NOTIFY信息(参阅下面的 Section 27.6)。

一个使用 PQsendQuery/PQgetResult 的客户端同样也可以试图取消一个正在被服务器处理的命令。

PQrequestCancel

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

int PQrequestCancel(PGconn *conn);

如果取消的请求成功发送,返回值是 1,否则是 0。 (如果为假,PQerrorMessage 会告之为什么。) 不过,取消请求的成功发送将不保证请求将产生作用。不管 PQrequestCancel 的返回值是什么,应用都必须继续使用 PQgetResult进行通常的后续的结果读取工作。 如果取消动作生效,当前的命令将提前退出并返回一个错误结果。 如果取消动作失败(也就是服务器已经处理完命令了),那么将没有可见的结果。

注意:如果当前的命令是事务的一部分,取消动作将退出整个事务。

PQrequestCancel 可以很安全地从一个信号句柄里调用。 所以,如果取消动作可以从信号句柄里发出的话,它也可以与简单的 PQexec一起使用。例如, psql 从一个SIGINT信号句柄里调用 PQrequestCancel ,因此允许交互地取消通过 PQexec 发出的查询。

通过使用上面描述的函数,我们可以避免在等待来自数据库服务器的时候的阻塞。 不过,应用还是有可能阻塞在给服务器发送输出上。这种情况比较少见,但是也可能发生, 尤其是我们要发送非常长的 SQL 命令或者数据值的时候。 (不过,最有可能的是在应用通过 COPY IN 发送数据的时候。) 为了避免这个可能性,实现完全的非阻塞数据库操作,我们可以使用下列额外的函数。

PQsetnonblocking

把连接的状态设置为非阻塞。

int PQsetnonblocking(PGconn *conn, int arg);

如果arg为 1,把连接状态设置为非阻塞, 如果arg为 0, 把连接状态设置为阻塞。如果 OK 返回 0,如果错误返回 -1。

在非阻塞状态,调用 PQputlinePQputnbytesPQsendQueryPQendcopy 的时候不被阻塞, 而是在如果需要再次调用它们时将返回一个错误。

请注意 PQexec 不会在意任何非阻塞模式; 如果调用了 PQexec,那么它的行为总是阻塞的。

PQisnonblocking

返回数据库连接的阻塞状态。

int PQisnonblocking(const PGconn *conn);

如果连接设置为非阻塞状态,返回 1,如果是阻塞状态返回 0。

PQflush

试图把任何正在排队的数据冲刷到服务器, 如果成功(或者发送队列为空)返回 0,如果因某种原因失败返回 -1, 或者是在无法把发送队列中的所有数据都发送出去,返回 1。 (这种情况只有在连接不为阻塞模式的时候才会出现)。

int PQflush(PGconn *conn);

在一个非阻塞的连接上发送任何命令或者数据之后, 调用PQflush 。 如果返回 1,就等待套接字写准备好然后再次调用;重复这个操作直到它返回 0。 一旦PQflush返回 0,则等待套接字为读准备好,准备好之后就像上面那样读取。