31.4. 异步命令处理 · PostgreSQL 中文文档 9.3

# 31.4\. 异步命令处理 `PQexec`函数对普通的同步应用里提交命令已经是足够用的了。但是它却有几个缺陷，而这些缺陷可能对某些用户很重要： * `PQexec`等待命令结束。而应用可能还有其它的工作要做（比如维护用户界面等），这个时候它可不想阻塞在这里等待响应。 * 因为客户端应用在等待结果的时候是处于挂起状态的，所以应用很难判断它是否该尝试结束正在进行的命令。（这个事情可以在一个信号处理器中做，但是没别的方法。） * `PQexec`只能返回一个`PGresult`结构。如果提交的命令字符串包含多个SQL命令，除了最后一个 `PGresult`以外都会被`PQexec`丢弃。 * `PQexec`总是收集命令的整个结果，将其缓存在一个`PGresult`中。虽然这为应用简化了错误处理逻辑，但是对于包含多行的结果是不切实际的。不想受到这些限制的应用可以改用下面的函数，这些函数也是构造`PQexec` 的函数：`PQsendQuery`和`PQgetResult`。也有`PQsendQueryParams`，`PQsendPrepare`， `PQsendQueryPrepared`，`PQsendDescribePrepared` 和`PQsendDescribePortal`，他们可以和`PQgetResult` 一起使用，分别用于复制`PQexecParams`，`PQprepare`， `PQexecPrepared`，`PQdescribePrepared` 和`PQdescribePortal`的功能。 `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` 等待从前面`PQsendQuery`，`PQsendQueryParams`， `PQsendPrepare`，`PQsendQueryPrepared`， `PQsendDescribePrepared`或者`PQsendDescribePortal` 调用返回的下一个结果，然后返回之。当命令结束并且没有更多结果后返回 NULL。 ``` PGresult *PQgetResult(PGconn *conn); ``` 必须重复的调用`PQgetResult`，直到它返回空指针，表明该命令结束。（如果在没有活跃的命令时调用，`PQgetResult`将只是立即返回一个空指针。）每个`PQgetResult`返回的非 NULL 结果都应该用前面描述的 `PGresult`访问函数进行分析。不要忘了在结束分析后用`PQclear` 释放每个结果对象。注意，`PQgetResult` 只是在有一个命令是活跃的而且必须返回数的据还没有被`PQconsumeInput`读取时阻塞。 > **Note:** 即使在`PQresultStatus`表明一个致命的错误时，也应该调用`PQgetResult`直到它返回一个空指针，以允许libpq完全的处理错误信息。使用`PQsendQuery`和`PQgetResult`解决了 `PQexec`的一个问题：如果一个命令字符串包含多个 SQL命令，这些命令的结果可以独立的获得。（这样就允许一种简单的重叠处理模式，顺便说一句：客户端可以处理一个命令的结果而服务器可以仍然在处理同一命令字符串后面的查询。）另一个可以用`PQsendQuery`和`PQgetResult` 获得的经常需要的特性是一次检索大型连续查询结果。这在 [Section 31.5](#calibre_link-626)中讨论。单独的，调用`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`信息（参阅[Section 31.8](#calibre_link-775)）。一个使用`PQsendQuery`/`PQgetResult` 的客户端同样也可以试图取消一个正在被服务器处理的命令。参阅[Section 31.6](#calibre_link-670)。但是，不管`PQcancel`返回的值是多少，应用都必须使用 `PQgetResult`进行正常的读取结果的动作序列。一次成功的取消只会导致命令比正常情况下快些结束。通过使用上面描述的函数，我们可以避免在等待来自数据库服务器的输入时的阻塞。不过，应用还是有可能阻塞在给服务器发送输出上。这种情况比较少见，但是也可能发生，尤其是我们要发送非常长的 SQL 命令或者数据值的时候。（不过，最有可能的是在应用通过`COPY IN`发送数据的时候。）为了避免这个可能性，实现完全的非阻塞数据库操作，我们可以使用下列额外的函数。 `PQsetnonblocking` 把连接的状态设置为非阻塞。 ``` int PQsetnonblocking(PGconn *conn, int arg); ``` 如果`arg`为 1，把连接状态设置为非阻塞，如果`arg`为 0，把连接状态设置为阻塞。如果 OK 返回 0，如果错误返回 -1。在非阻塞状态，调用`PQsendQuery`，`PQputline`， `PQputnbytes`，和`PQendcopy`的时候不被阻塞，而是在如果需要再次调用它们时将返回一个错误。请注意`PQexec`不会在意任何非阻塞模式；如果调用了 `PQexec`，那么它的行为总是阻塞的。 `PQisnonblocking` 返回数据库连接的阻塞状态。 ``` int PQisnonblocking(const PGconn *conn); ``` 如果连接设置为非阻塞状态，返回 1，如果是阻塞状态返回 0。 `PQflush` 试图把任何正在排队的数据冲刷到服务器，如果成功（或者发送队列为空）返回 0，如果因某种原因失败返回 -1，或者是在无法把发送队列中的所有数据都发送出去，返回 1。（这种情况只有在连接为不阻塞模式的时候才会出现）。 ``` int PQflush(PGconn *conn); ``` 在一个非阻塞的连接上发送任何命令或者数据之后，调用`PQflush`。如果返回 1，就等待套接字写准备好然后再次调用；重复这个操作直到它返回 0。一旦`PQflush`返回 0，则等待套接字为读准备好，准备好之后就像上面那样读取响应。