Postgresql 中文操作指南

34.8. The Fast-Path Interface #

PostgreSQL 提供了一个快速路径接口，用于向服务器发送简单的函数调用。

PostgreSQL provides a fast-path interface to send simple function calls to the server.

Tip

此接口有些过时，因为可以通过设置预定义语句来定义函数调用以获得类似的性能和更强大的功能。然后，使用二进制方式传输参数和结果来执行此语句，代替快速路径函数调用。

This interface is somewhat obsolete, as one can achieve similar performance and greater functionality by setting up a prepared statement to define the function call. Then, executing the statement with binary transmission of parameters and results substitutes for a fast-path function call.

PQfn 函数通过快速路径接口请求执行服务器函数：

The function PQfn requests execution of a server function via the fast-path interface:

PGresult *PQfn(PGconn *conn,
               int fnid,
               int *result_buf,
               int *result_len,
               int result_is_int,
               const PQArgBlock *args,
               int nargs);

typedef struct
{
    int len;
    int isint;
    union
    {
        int *ptr;
        int integer;
    } u;
} PQArgBlock;

fnid 参数是被执行函数的 OID。args 和 nargs 定义了要传递给函数的参数，它们必须与已声明的函数参数列表匹配。当参数结构的 isint 字段为真时，u.integer 值将作为指定长度的整数发送给服务器（这必须是 2 或 4 个字节）；会进行适当的字节交换。当 isint 为假时，*u.ptr 处指定数量的字节将被发送，而不会进行任何处理；数据必须采用服务器所期望的格式，以进行函数参数数据类型的二进制传输。（将 u.ptr 声明为 int * 类型是一种历史习惯；最好将其视为 void *。）result_buf 指向用于放置函数返回值的缓冲区。调用方必须分配足够的存储空间来存储返回值。（这里没有检查！）以字节为单位的实际结果长度将返回到 result_len 所指向的整数中。如果预期结果为 2 或 4 字节整数，则将 result_is_int 设置为 1，否则将其设置为 0。将 result_is_int 设置为 1 将导致 libpq 在必要时对值进行字节交换，以便将其作为合适的 int 值发送给客户端计算机；请注意，对于任何允许的结果大小，4 字节整数将被发送到 *result_buf 中。当 result_is_int 为 0 时，服务器发送的二进制格式字节字符串将原样返回。（在这种情况下，最好将 result_buf 视为 void * 类型。）

The fnid argument is the OID of the function to be executed. args and nargs define the parameters to be passed to the function; they must match the declared function argument list. When the isint field of a parameter structure is true, the u.integer value is sent to the server as an integer of the indicated length (this must be 2 or 4 bytes); proper byte-swapping occurs. When isint is false, the indicated number of bytes at *u.ptr are sent with no processing; the data must be in the format expected by the server for binary transmission of the function’s argument data type. (The declaration of u.ptr as being of type int * is historical; it would be better to consider it void *.) result_buf points to the buffer in which to place the function’s return value. The caller must have allocated sufficient space to store the return value. (There is no check!) The actual result length in bytes will be returned in the integer pointed to by result_len. If a 2- or 4-byte integer result is expected, set result_is_int to 1, otherwise set it to 0. Setting result_is_int to 1 causes libpq to byte-swap the value if necessary, so that it is delivered as a proper int value for the client machine; note that a 4-byte integer is delivered into *result_buf for either allowed result size. When result_is_int is 0, the binary-format byte string sent by the server is returned unmodified. (In this case it’s better to consider result_buf as being of type void *.)

PQfn 始终返回有效的 PGresult 指针，其中 PGRES_COMMAND_OK 表示成功， PGRES_FATAL_ERROR 表示遇到某些问题。使用结果之前，应检查结果状态。在不再需要 PGresult 时，调用方负责使用 PQclear 释放它。

PQfn always returns a valid PGresult pointer, with status PGRES_COMMAND_OK for success or PGRES_FATAL_ERROR if some problem was encountered. The result status should be checked before the result is used. The caller is responsible for freeing the PGresult with PQclear when it is no longer needed.

要将 NULL 参数传递给函数，请将该参数结构的 len 字段设置为 -1；则 isint 和 u 字段将不相关。

To pass a NULL argument to the function, set the len field of that parameter structure to -1; the isint and u fields are then irrelevant.

如果函数返回 NULL，则 *result_len 将设置为 -1，并且 *result_buf 将不会被修改。

If the function returns NULL, *result_len is set to -1, and *result_buf is not modified.

请注意，使用此接口时无法处理集值结果。此外，函数必须是普通函数，而不是聚合函数、窗口函数或过程。

Note that it is not possible to handle set-valued results when using this interface. Also, the function must be a plain function, not an aggregate, window function, or procedure.