PostgreSQL 中文参考文档
🌐 英文原版 官方 ↗

32.8. Fast-Path 快速通道接口 #

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

Warning

这个接口是不安全的, 不应当被使用。 当 result_is_int 被设置为 0 时, PQfn 可能会把数据写到 result_buf 的末尾之外, 而不管该缓冲区是否有足够的空间容纳所请求数量的字节。 此外, 它已经过时了, 因为通过建立一个已准备语句来定义函数调用, 可以获得类似的性能和更多的功能。 然后, 以二进制方式传输参数和结果来执行该语句, 就可以取代一次快速路径函数调用。

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

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 值被交付; 注意, 无论允许的结果尺寸是哪个, 交付到 *result_buf 中的都是一个 4 字节整数。 当 result_is_int 为 0 时, 服务器发送的二进制格式字节字符串会被不加修改地返回。 (在这种情况下, 最好把 result_buf 视为 void * 类型。)

PQfn 总是返回一个有效的 PGresult 指针, 成功时状态为 PGRES_COMMAND_OK, 遇到某些问题时为 PGRES_FATAL_ERROR。 在使用结果之前应当检查结果状态。 当不再需要该 PGresult 时, 调用者有责任用 PQclear 释放它。

要向函数传递一个 NULL 参数, 把那个参数结构的 len 字段设置为 -1; 此时 isint 和 u 字段就无关紧要了。

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

注意,在使用这个接口时无法处理集合值的结果。 此外, 该函数必须是一个普通函数, 不能是聚集、窗口函数或过程。