31.4. 异步命令处理

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

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

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 版本的协议连接上工作。

PQsendDescribePrepared

提交一个请求,获取关于指定的预备语句的信息,不等待结果。

int PQsendDescribePrepared(PGconn *conn, const char *stmtName);

这是PQdescribePrepared的一个异步版本:如果它能发送这个请求,则返回 1, 如果不能,则返回 0。在成功调用之后,调用PQgetResult获取结果。 这个函数的参数的处理和PQdescribePrepared一样。 类似PQdescribePrepared,它不能在 2.0 版本协议的连接上运转。

PQsendDescribePortal

发出请求,以获得关于指定端口的信息,不需要等待完成。

int PQsendDescribePortal(PGconn *conn, const char *portalName);

这是一个PQdescribePortal的异步版本:如果它能发送这个请求,那么返回1, 否则返回0。成功调用之后,通过PQgetResult获得结果。 函数参数处理与PQdescribePortal相同。 类似于PQdescribePortal,不能在2.0的协议连接上工作。

PQgetResult

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

PGresult *PQgetResult(PGconn *conn);

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

注意: 即使在PQresultStatus表明一个致命的错误时, 也应该调用PQgetResult直到它返回一个空指针, 以允许libpq完全的处理错误消息。

使用PQsendQueryPQgetResult解决了 PQexec的一个问题:如果一个命令字符串包含多个 SQL命令,这些命令的结果可以独立的获得。(这样就允许一种简单的重叠处理模式, 顺便说一句:客户端可以处理一个命令的结果而服务器可以仍然在处理同一命令字符串后面的查询。)

另一个可以用PQsendQueryPQgetResult 获得的经常需要的特性是一次检索大型连续查询结果。这在 第 31.5 节中讨论。

单独的,调用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()poll()等待所有它必须处理的条件。其中一个条件将会是服务器来的数据已准备好, 从select()的角度来看就是PQsocket 标识的文件描述符上已经有可读取的数据。当主循环侦测到输入准备好, 它将调用PQconsumeInput读取输入。然后可以调用PQisBusy, 返回 false (0)后面可以跟着PQgetResult。同样它(用户应用) 可以调用PQnotifies检测NOTIFY信息 (参阅第 31.8 节)。

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

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

PQsetnonblocking

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

int PQsetnonblocking(PGconn *conn, int arg);

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

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

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

PQisnonblocking

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

int PQisnonblocking(const PGconn *conn);

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

PQflush

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

int PQflush(PGconn *conn);

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