27.4. 异步命令处理

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

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

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 版本的协议连接上工作,并且它只允许在查询字串里出现一条命令。

PQsendPrepare

发送一个请求,创建一个给定参数的准备好语句,而不等待结束。

int PQsendPrepare(PGconn *conn,
                  const char *stmtName,
                  const char *query,
                  int nParams,
                  const Oid *paramTypes);

这是 PQprepare 的异步版本:如果它能发送这个请求,则返回 1, 如果不能,则返回 0。在成功调用之后,调用 PQgetResult 判断服务器是否成功创建了准备好语句。 这个函数的参数的处理和 PQprepare 一样。 类似 PQprepare,它不能在 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

等待从前面 PQsendQueryPQsendQueryParamsPQsendPrepare, 或者 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.7)。

一个使用 PQsendQuery/PQgetResult 的客户端同样也可以试图取消一个正在被服务器处理的命令。参阅 Section 27.5。 但是,不管 PQcancel 返回的值是多少,应用都必须使用 PQgetResult 进行正常的读取结果的动作序列。 一次成功的取消只会导致命令比正常情况下快些结束。

通过使用上面描述的函数,我们可以避免在等待来自数据库服务器的时候的阻塞。 不过,应用还是有可能阻塞在给服务器发送输出上。这种情况比较少见,但是也可能发生, 尤其是我们要发送非常长的 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,则等待套接字为读准备好,准备好之后就像上面那样读取。