会话中首次调用特定可加载对象文件中的用户定义函数时，动态加载器将该对象文件加载到内存中，以便可以调用该函数。因此，用户定义 C 函数的 CREATE FUNCTION 必须为该函数指定两部分信息：可加载对象文件的名称，以及该对象文件中要调用的特定函数的 C 名称（链接符号）。如果未明确指定 C 名称，则假定它与 SQL 函数名称相同。

根据 CREATE FUNCTION 命令中给出的名称来定位共享对象文件使用以下算法

如果此序列不起作用，则会将平台特定的共享库文件扩展名（通常为 .so）附加到给定名称，并再次尝试此序列。如果也失败，则加载将失败。

建议将共享库相对于 $libdir 或通过动态库路径定位。如果新安装在不同的位置，这会简化版本升级。$libdir 所代表的实际目录可以通过命令 pg_config --pkglibdir 查明。

PostgreSQL 服务器运行的用户 ID 必须能够遍历到您打算加载的文件路径。使文件或更高级别目录对 postgres 用户不可读和/或不可执行是一个常见的错误。

无论如何，CREATE FUNCTION 命令中给出的文件名将原封不动地记录在系统目录中，因此如果需要再次加载文件，将应用相同的过程。

为确保动态加载的对象文件不会加载到不兼容的服务器中，PostgreSQL 会检查该文件是否包含具有适当内容的“魔术块”。这允许服务器检测明显的兼容性问题，例如为不同主要版本的 PostgreSQL 编译的代码。要包含魔术块，请在模块的其中一个（且仅一个）源文件中写入以下内容，在包含头文件 fmgr.h 之后

PG_MODULE_MAGIC;

或

PG_MODULE_MAGIC_EXT(parameters);

PG_MODULE_MAGIC_EXT 变体允许指定有关模块的附加信息；目前，可以添加名称和/或版本字符串。（将来可能会允许更多字段。）编写如下所示

PG_MODULE_MAGIC_EXT(
    .name = "my_module_name",
    .version = "1.2.3"
);

随后可以通过 pg_get_loaded_modules() 函数检查名称和版本。PostgreSQL 不限制版本字符串的含义，但建议使用语义版本控制规则。

首次使用后，动态加载的对象文件将保留在内存中。在同一会话中对该文件中函数进行后续调用只会产生符号表查找的小开销。如果您需要强制重新加载对象文件，例如在重新编译后，请启动一个新的会话。

或者，动态加载的文件可以包含一个初始化函数。如果文件包含名为 _PG_init 的函数，则该函数将在加载文件后立即调用。该函数不接收任何参数，并且应返回 void。目前无法卸载动态加载的文件。

要了解如何编写 C 语言函数，您需要了解 PostgreSQL 如何在内部表示基本数据类型以及它们如何传递给函数和从函数返回。在内部，PostgreSQL 将基本类型视为“内存块”。您在类型上定义的用户定义函数反过来定义了 PostgreSQL 如何对其进行操作。也就是说，PostgreSQL 只会从磁盘存储和检索数据，并使用您的用户定义函数来输入、处理和输出数据。

基本类型可以有三种内部格式

按值传递的类型长度只能是 1、2 或 4 字节（如果您的机器上 sizeof(Datum) 为 8，也可以是 8 字节）。您应该注意定义您的类型，使其在所有架构上都具有相同的大小（以字节为单位）。例如，long 类型是危险的，因为它在某些机器上是 4 字节，在其他机器上是 8 字节，而 int 类型在大多数 Unix 机器上是 4 字节。在 Unix 机器上 int4 类型的一个合理实现可能是

/* 4-byte integer, passed by value */
typedef int int4;

（实际的 PostgreSQL C 代码将此类型称为 int32，因为在 C 语言中 intXX 表示 XX 位。因此还要注意 C 类型 int8 的大小为 1 字节。SQL 类型 int8 在 C 语言中称为 int64。另请参阅 表 36.2。）

另一方面，任意大小的固定长度类型可以通过引用传递。例如，这是一个 PostgreSQL 类型的一个示例实现

/* 16-byte structure, passed by reference */
typedef struct
{
    double  x, y;
} Point;

在将此类类型传递进出 PostgreSQL 函数时，只能使用指向此类类型的指针。要返回此类类型的值，请使用 palloc 分配正确的内存量，填充分配的内存，并返回指向它的指针。（此外，如果您只想返回与相同数据类型的输入参数之一相同的值，则可以跳过额外的 palloc，只返回指向输入值的指针。）

最后，所有变长类型也必须通过引用传递。所有变长类型必须以一个精确为 4 字节的不透明长度字段开头，该字段将由 SET_VARSIZE 设置；切勿直接设置此字段！存储在该类型内的所有数据必须位于该长度字段紧随其后的内存中。长度字段包含结构的总长度，也就是说，它包括长度字段本身的大小。

另一个重要点是避免在数据类型值中留下任何未初始化的位；例如，注意将结构中可能存在的任何对齐填充字节清零。否则，您的数据类型的逻辑等价常量可能会被规划器视为不相等，从而导致低效（但不错误）的计划。

例如，我们可以将 text 类型定义如下

typedef struct {
    int32 length;
    char data[FLEXIBLE_ARRAY_MEMBER];
} text;

[FLEXIBLE_ARRAY_MEMBER] 符号表示数据部分的实际长度未由此声明指定。

在操作变长类型时，我们必须小心分配正确的内存量并正确设置长度字段。例如，如果我们想在 text 结构中存储 40 字节，我们可能会使用如下代码片段

#include "postgres.h"
...
char buffer[40]; /* our source data */
...
text *destination = (text *) palloc(VARHDRSZ + 40);
SET_VARSIZE(destination, VARHDRSZ + 40);
memcpy(destination->data, buffer, 40);
...

VARHDRSZ 与 sizeof(int32) 相同，但使用宏 VARHDRSZ 来引用变长类型的开销大小被认为是良好的风格。此外，长度字段必须使用 SET_VARSIZE 宏设置，而不是通过简单的赋值。

表 36.2 显示了许多 PostgreSQL 内置 SQL 数据类型对应的 C 类型。“定义于”列给出了需要包含以获取类型定义的头文件。（实际定义可能在由列出的文件包含的其他文件中。建议用户坚持定义的接口。）请注意，在任何服务器代码源文件中，您应该始终首先包含 postgres.h，因为它声明了您无论如何都会需要的许多东西，并且首先包含其他头文件可能会导致可移植性问题。

现在我们已经介绍了基本类型的所有可能结构，我们可以展示一些实际函数的示例。

版本 1 调用约定依赖宏来抑制大部分传递参数和结果的复杂性。版本 1 函数的 C 声明始终是

Datum funcname(PG_FUNCTION_ARGS)

此外，宏调用

PG_FUNCTION_INFO_V1(funcname);

必须出现在同一个源文件中。（按照惯例，它通常写在函数本身之前。）对于 internal 语言函数，不需要此宏调用，因为 PostgreSQL 假定所有内部函数都使用版本 1 约定。但是，对于动态加载的函数，它却是必需的。

在版本 1 函数中，每个实际参数都使用与参数数据类型对应的 PG_GETARG_xxx() 宏获取。（在非严格函数中，需要先使用 PG_ARGISNULL() 检查参数是否为 NULL；请参见下文。）结果使用返回类型的 PG_RETURN_xxx() 宏返回。PG_GETARG_xxx() 将要获取的函数参数编号作为其参数，计数从 0 开始。PG_RETURN_xxx() 将要返回的实际值作为其参数。

要调用另一个版本 1 函数，可以使用 DirectFunctionCalln(func, arg1, ..., argn)。当您想调用标准内部库中定义的函数时，这特别有用，使用与它们的 SQL 签名类似的接口。

这些便利函数和类似函数可以在 fmgr.h 中找到。DirectFunctionCalln 系列将 C 函数名作为其第一个参数。还有 OidFunctionCalln 接受目标函数的 OID，以及其他一些变体。所有这些都期望函数的参数作为 Datum 提供，并且它们也返回 Datum。请注意，使用这些便利函数时，参数和结果都不能为 NULL。

例如，要从 C 调用 starts_with(text, text) 函数，您可以搜索目录并发现其 C 实现是 Datum text_starts_with(PG_FUNCTION_ARGS) 函数。通常，您会使用 DirectFunctionCall2(text_starts_with, ...) 来调用此类函数。但是，starts_with(text, text) 需要排序规则信息，因此如果以这种方式调用，它将失败并出现“无法确定用于字符串比较的排序规则”错误。相反，您必须使用 DirectFunctionCall2Coll(text_starts_with, ...) 并提供所需的排序规则，通常只是从 PG_GET_COLLATION() 传递，如下例所示。

fmgr.h 还提供了方便 C 类型和 Datum 之间转换的宏。例如，要将 Datum 转换为 text*，可以使用 DatumGetTextPP(X)。虽然某些类型有像 TypeGetDatum(X) 这样的宏用于反向转换，但 text* 没有；为此，使用通用宏 PointerGetDatum(X) 就足够了。如果您的扩展定义了其他类型，通常也方便为您的类型定义类似的宏。

以下是使用版本 1 调用约定的一些示例

#include "postgres.h"
#include <string.h>
#include "fmgr.h"
#include "utils/geo_decls.h"
#include "varatt.h"

PG_MODULE_MAGIC;

/* by value */

PG_FUNCTION_INFO_V1(add_one);

Datum
add_one(PG_FUNCTION_ARGS)
{
    int32   arg = PG_GETARG_INT32(0);

    PG_RETURN_INT32(arg + 1);
}

/* by reference, fixed length */

PG_FUNCTION_INFO_V1(add_one_float8);

Datum
add_one_float8(PG_FUNCTION_ARGS)
{
    /* The macros for FLOAT8 hide its pass-by-reference nature. */
    float8   arg = PG_GETARG_FLOAT8(0);

    PG_RETURN_FLOAT8(arg + 1.0);
}

PG_FUNCTION_INFO_V1(makepoint);

Datum
makepoint(PG_FUNCTION_ARGS)
{
    /* Here, the pass-by-reference nature of Point is not hidden. */
    Point     *pointx = PG_GETARG_POINT_P(0);
    Point     *pointy = PG_GETARG_POINT_P(1);
    Point     *new_point = (Point *) palloc(sizeof(Point));

    new_point->x = pointx->x;
    new_point->y = pointy->y;

    PG_RETURN_POINT_P(new_point);
}

/* by reference, variable length */

PG_FUNCTION_INFO_V1(copytext);

Datum
copytext(PG_FUNCTION_ARGS)
{
    text     *t = PG_GETARG_TEXT_PP(0);

    /*
     * VARSIZE_ANY_EXHDR is the size of the struct in bytes, minus the
     * VARHDRSZ or VARHDRSZ_SHORT of its header.  Construct the copy with a
     * full-length header.
     */
    text     *new_t = (text *) palloc(VARSIZE_ANY_EXHDR(t) + VARHDRSZ);
    SET_VARSIZE(new_t, VARSIZE_ANY_EXHDR(t) + VARHDRSZ);

    /*
     * VARDATA is a pointer to the data region of the new struct.  The source
     * could be a short datum, so retrieve its data through VARDATA_ANY.
     */
    memcpy(VARDATA(new_t),          /* destination */
           VARDATA_ANY(t),          /* source */
           VARSIZE_ANY_EXHDR(t));   /* how many bytes */
    PG_RETURN_TEXT_P(new_t);
}

PG_FUNCTION_INFO_V1(concat_text);

Datum
concat_text(PG_FUNCTION_ARGS)
{
    text  *arg1 = PG_GETARG_TEXT_PP(0);
    text  *arg2 = PG_GETARG_TEXT_PP(1);
    int32 arg1_size = VARSIZE_ANY_EXHDR(arg1);
    int32 arg2_size = VARSIZE_ANY_EXHDR(arg2);
    int32 new_text_size = arg1_size + arg2_size + VARHDRSZ;
    text *new_text = (text *) palloc(new_text_size);

    SET_VARSIZE(new_text, new_text_size);
    memcpy(VARDATA(new_text), VARDATA_ANY(arg1), arg1_size);
    memcpy(VARDATA(new_text) + arg1_size, VARDATA_ANY(arg2), arg2_size);
    PG_RETURN_TEXT_P(new_text);
}

/* A wrapper around starts_with(text, text) */

PG_FUNCTION_INFO_V1(t_starts_with);

Datum
t_starts_with(PG_FUNCTION_ARGS)
{
    text       *t1 = PG_GETARG_TEXT_PP(0);
    text       *t2 = PG_GETARG_TEXT_PP(1);
    Oid         collid = PG_GET_COLLATION();
    bool        result;

    result = DatumGetBool(DirectFunctionCall2Coll(text_starts_with,
                                                  collid,
                                                  PointerGetDatum(t1),
                                                  PointerGetDatum(t2)));
    PG_RETURN_BOOL(result);
}

假设以上代码已在文件 funcs.c 中准备并编译成共享对象，我们可以使用如下命令将这些函数定义到 PostgreSQL 中

CREATE FUNCTION add_one(integer) RETURNS integer
     AS 'DIRECTORY/funcs', 'add_one'
     LANGUAGE C STRICT;

-- note overloading of SQL function name "add_one"
CREATE FUNCTION add_one(double precision) RETURNS double precision
     AS 'DIRECTORY/funcs', 'add_one_float8'
     LANGUAGE C STRICT;

CREATE FUNCTION makepoint(point, point) RETURNS point
     AS 'DIRECTORY/funcs', 'makepoint'
     LANGUAGE C STRICT;

CREATE FUNCTION copytext(text) RETURNS text
     AS 'DIRECTORY/funcs', 'copytext'
     LANGUAGE C STRICT;

CREATE FUNCTION concat_text(text, text) RETURNS text
     AS 'DIRECTORY/funcs', 'concat_text'
     LANGUAGE C STRICT;

CREATE FUNCTION t_starts_with(text, text) RETURNS boolean
     AS 'DIRECTORY/funcs', 't_starts_with'
     LANGUAGE C STRICT;

这里，DIRECTORY 代表共享库文件的目录（例如 PostgreSQL 教程目录，其中包含本节中使用的示例代码）。（更好的风格是在 AS 子句中只使用 'funcs'，在将 DIRECTORY 添加到搜索路径之后。无论如何，我们可以省略共享库的系统特定扩展名，通常是 .so。）

请注意，我们已将函数指定为“严格”，这意味着如果任何输入值为 null，系统应自动假定结果为 null。通过这样做，我们避免了在函数代码中检查 null 输入。否则，我们必须使用 PG_ARGISNULL() 显式检查 null 值。

宏 PG_ARGISNULL(n) 允许函数测试每个输入是否为 null。（当然，这样做只在未声明为“严格”的函数中是必要的。）与 PG_GETARG_xxx() 宏一样，输入参数从零开始计数。请注意，在验证参数不为 null 之前，应避免执行 PG_GETARG_xxx()。要返回 null 结果，请执行 PG_RETURN_NULL()；这在严格和非严格函数中都有效。

乍一看，版本 1 编码约定与使用普通的 C 调用约定相比，可能显得毫无意义的晦涩。然而，它们确实允许我们处理可为空的参数/返回值以及“toasted”（压缩或行外）值。

版本 1 接口提供的其他选项是 PG_GETARG_xxx() 宏的两个变体。其中第一个，PG_GETARG_xxx_COPY()，保证返回指定参数的副本，该副本可安全写入。（普通宏有时会返回指向物理存储在表中的值的指针，该值不得写入。使用 PG_GETARG_xxx_COPY() 宏保证可写入结果。）第二个变体由 PG_GETARG_xxx_SLICE() 宏组成，它接受三个参数。第一个是函数参数的编号（如上所述）。第二个和第三个是要返回的段的偏移量和长度。偏移量从零开始计数，负长度请求返回值的其余部分。在值具有存储类型“external”的情况下，这些宏提供了对大值部分的更高效访问。（列的存储类型可以使用 ALTER TABLE tablename ALTER COLUMN colname SET STORAGE storagetype 指定。storagetype 是 plain、external、extended 或 main 之一。）

最后，版本 1 函数调用约定使得返回集合结果（第 36.10.9 节）并实现触发器函数（第 37 章）和过程语言调用处理程序（第 57 章）成为可能。有关更多详细信息，请参阅源代码分发中的 src/backend/utils/fmgr/README。

在转向更高级的主题之前，我们应该讨论一些 PostgreSQL C 语言函数的编码规则。虽然可能可以将用 C 以外的语言编写的函数加载到 PostgreSQL 中，但这通常很困难（如果可能的话），因为其他语言，例如 C++、FORTRAN 或 Pascal，通常不遵循与 C 相同的调用约定。也就是说，其他语言在函数之间传递参数和返回值的方式不同。因此，我们将假设您的 C 语言函数实际上是用 C 编写的。

编写和构建 C 函数的基本规则如下

在使用用 C 语言编写的 PostgreSQL 扩展函数之前，必须以特殊方式编译和链接它们，以生成可由服务器动态加载的文件。确切地说，需要创建一个共享库。

除了本节中包含的信息之外，您还应该阅读操作系统的文档，特别是 C 编译器 cc 和链接编辑器 ld 的手册页。此外，PostgreSQL 源代码的 contrib 目录中包含几个工作示例。但是，如果您依赖这些示例，您的模块将依赖于 PostgreSQL 源代码的可用性。

创建共享库通常类似于链接可执行文件：首先将源文件编译为对象文件，然后将对象文件链接在一起。对象文件需要创建为位置无关代码（PIC），这在概念上意味着当它们被可执行文件加载时，它们可以放置在内存中的任意位置。（用于可执行文件的对象文件通常不是这样编译的。）链接共享库的命令包含特殊标志，以将其与链接可执行文件区分开来（至少在理论上是这样——在某些系统上，实际情况要复杂得多）。

在以下示例中，我们假设您的源代码位于文件 foo.c 中，我们将创建一个共享库 foo.so。除非另有说明，否则中间对象文件将命名为 foo.o。共享库可以包含多个对象文件，但我们此处只使用一个。

生成的共享库文件随后可以加载到 PostgreSQL 中。在向 CREATE FUNCTION 命令指定文件名时，必须提供共享库文件的名称，而不是中间对象文件的名称。请注意，系统标准共享库扩展名（通常是 .so 或 .sl）可以从 CREATE FUNCTION 命令中省略，并且通常为了最佳可移植性应省略。

请参阅 第 36.10.1 节，了解服务器期望在哪里找到共享库文件。

本节包含关于 PostgreSQL 服务器中 API 和 ABI 稳定性的扩展和其他服务器插件作者指南。

复合类型没有像 C 结构那样的固定布局。复合类型的实例可以包含空字段。此外，作为继承层次结构一部分的复合类型可以具有与同一继承层次结构的其他成员不同的字段。因此，PostgreSQL 提供了一个函数接口，用于从 C 语言访问复合类型的字段。

假设我们想编写一个函数来回答以下查询

SELECT name, c_overpaid(emp, 1500) AS overpaid
    FROM emp
    WHERE name = 'Bill' OR name = 'Sam';

使用版本 1 调用约定，我们可以将 c_overpaid 定义为

#include "postgres.h"
#include "executor/executor.h"  /* for GetAttributeByName() */

PG_MODULE_MAGIC;

PG_FUNCTION_INFO_V1(c_overpaid);

Datum
c_overpaid(PG_FUNCTION_ARGS)
{
    HeapTupleHeader  t = PG_GETARG_HEAPTUPLEHEADER(0);
    int32            limit = PG_GETARG_INT32(1);
    bool isnull;
    Datum salary;

    salary = GetAttributeByName(t, "salary", &isnull);
    if (isnull)
        PG_RETURN_BOOL(false);
    /* Alternatively, we might prefer to do PG_RETURN_NULL() for null salary. */

    PG_RETURN_BOOL(DatumGetInt32(salary) > limit);
}

GetAttributeByName 是 PostgreSQL 系统函数，它从指定行中返回属性。它有三个参数：传入函数的 HeapTupleHeader 类型的参数，所需属性的名称，以及一个指示属性是否为空的返回参数。GetAttributeByName 返回一个 Datum 值，您可以使用适当的 DatumGetXXX() 函数将其转换为正确的数据类型。请注意，如果设置了空标志，则返回值是无意义的；在尝试对结果进行任何操作之前，请务必检查空标志。

还有 GetAttributeByNum，它通过列号而不是名称选择目标属性。

以下命令在 SQL 中声明函数 c_overpaid

CREATE FUNCTION c_overpaid(emp, integer) RETURNS boolean
    AS 'DIRECTORY/funcs', 'c_overpaid'
    LANGUAGE C STRICT;

请注意，我们使用了 STRICT，这样就不必检查输入参数是否为 NULL。

要从 C 语言函数返回行或复合类型值，您可以使用一个特殊 API，该 API 提供了宏和函数来隐藏构建复合数据类型的大部分复杂性。要使用此 API，源文件必须包含

#include "funcapi.h"

有两种方法可以构建复合数据值（此后称为“元组”）：您可以从 Datum 值数组构建它，或者从 C 字符串数组构建它，这些 C 字符串可以传递给元组列数据类型的输入转换函数。在任何一种情况下，您首先需要获取或构造元组结构的 TupleDesc 描述符。使用 Datums 时，将 TupleDesc 传递给 BlessTupleDesc，然后为每一行调用 heap_form_tuple。使用 C 字符串时，将 TupleDesc 传递给 TupleDescGetAttInMetadata，然后为每一行调用 BuildTupleFromCStrings。对于返回元组集的函数，设置步骤可以在函数第一次调用时全部完成。

有几个辅助函数可用于设置所需的 TupleDesc。在大多数返回复合值的函数中，推荐的方法是调用

TypeFuncClass get_call_result_type(FunctionCallInfo fcinfo,
                                   Oid *resultTypeId,
                                   TupleDesc *resultTupleDesc)

传入与调用函数本身相同的 fcinfo 结构。（这当然要求您使用版本 1 调用约定。）resultTypeId 可以指定为 NULL 或局部变量的地址，以接收函数的返回类型 OID。resultTupleDesc 应该是一个局部 TupleDesc 变量的地址。检查结果是否为 TYPEFUNC_COMPOSITE；如果是，则 resultTupleDesc 已填充所需的 TupleDesc。（如果不是，您可以报告类似“函数在无法接受类型记录的上下文中调用记录”的错误。）

获取 TupleDesc 的旧版（现已弃用）函数是

TupleDesc RelationNameGetTupleDesc(const char *relname)

以获取命名关系的行类型的 TupleDesc，以及

TupleDesc TypeGetTupleDesc(Oid typeoid, List *colaliases)

基于类型 OID 获取 TupleDesc。这可用于获取基本类型或复合类型的 TupleDesc。但是，它不适用于返回 record 的函数，并且无法解析多态类型。

一旦您拥有 TupleDesc，请调用

TupleDesc BlessTupleDesc(TupleDesc tupdesc)

如果您打算使用 Datum，或者

AttInMetadata *TupleDescGetAttInMetadata(TupleDesc tupdesc)

如果您打算使用 C 字符串。如果您正在编写返回集合的函数，则可以将这些函数的结果保存在 FuncCallContext 结构中——分别使用 tuple_desc 或 attinmeta 字段。

使用 Datum 时，使用

HeapTuple heap_form_tuple(TupleDesc tupdesc, Datum *values, bool *isnull)

以 Datum 形式给定用户数据来构建 HeapTuple。

当使用 C 字符串时，使用

HeapTuple BuildTupleFromCStrings(AttInMetadata *attinmeta, char **values)

根据 C 字符串形式的用户数据构建 HeapTuple。values 是一个 C 字符串数组，返回行的每个属性一个。每个 C 字符串都应采用属性数据类型的输入函数所期望的格式。为了返回其中一个属性的空值，values 数组中对应的指针应设置为 NULL。对于您返回的每一行，都需要再次调用此函数。

一旦您构建了一个要从函数返回的元组，它就必须转换为 Datum。使用

HeapTupleGetDatum(HeapTuple tuple)

将 HeapTuple 转换为有效的 Datum。如果您只打算返回一行，则可以直接返回此 Datum，或者可以在返回集合的函数中将其用作当前返回值。

下一节将出现一个示例。

C 语言函数有两种返回集合（多行）的选项。在一种称为按调用返回值模式的方法中，集合返回函数被重复调用（每次传递相同的参数），并在每次调用时返回一个新行，直到它没有更多行要返回并通过返回 NULL 来发出信号。因此，集合返回函数（SRF）必须在调用之间保存足够的状态，以记住它正在做什么并在每次调用时返回正确的下一个项目。在另一种称为具体化模式的方法中，SRF 填充并返回一个包含其整个结果的元组存储对象；然后只发生一次对整个结果的调用，并且不需要调用间状态。

在使用按调用返回值模式时，记住不能保证查询会运行完成是很重要的；也就是说，由于 LIMIT 等选项，执行器可能会在所有行都被获取之前停止对集合返回函数的调用。这意味着在最后一次调用中执行清理活动是不安全的，因为这可能永远不会发生。对于需要访问外部资源（例如文件描述符）的函数，建议使用具体化模式。

本节的其余部分文档了一组通常用于（但不是必须使用）使用 ValuePerCall 模式的 SRF 的辅助宏。有关 Materialize 模式的更多详细信息，请参阅 src/backend/utils/fmgr/README。此外，PostgreSQL 源代码发行版中的 contrib 模块包含许多使用 ValuePerCall 和 Materialize 模式的 SRF 示例。

要使用此处描述的 ValuePerCall 支持宏，请包含 funcapi.h。这些宏使用 FuncCallContext 结构，该结构包含需要在调用之间保存的状态。在调用 SRF 中，fcinfo->flinfo->fn_extra 用于在调用之间保存指向 FuncCallContext 的指针。这些宏在第一次使用时自动填充该字段，并在后续使用时期望在那里找到相同的指针。

typedef struct FuncCallContext
{
    /*
     * Number of times we've been called before
     *
     * call_cntr is initialized to 0 for you by SRF_FIRSTCALL_INIT(), and
     * incremented for you every time SRF_RETURN_NEXT() is called.
     */
    uint64 call_cntr;

    /*
     * OPTIONAL maximum number of calls
     *
     * max_calls is here for convenience only and setting it is optional.
     * If not set, you must provide alternative means to know when the
     * function is done.
     */
    uint64 max_calls;

    /*
     * OPTIONAL pointer to miscellaneous user-provided context information
     *
     * user_fctx is for use as a pointer to your own data to retain
     * arbitrary context information between calls of your function.
     */
    void *user_fctx;

    /*
     * OPTIONAL pointer to struct containing attribute type input metadata
     *
     * attinmeta is for use when returning tuples (i.e., composite data types)
     * and is not used when returning base data types. It is only needed
     * if you intend to use BuildTupleFromCStrings() to create the return
     * tuple.
     */
    AttInMetadata *attinmeta;

    /*
     * memory context used for structures that must live for multiple calls
     *
     * multi_call_memory_ctx is set by SRF_FIRSTCALL_INIT() for you, and used
     * by SRF_RETURN_DONE() for cleanup. It is the most appropriate memory
     * context for any memory that is to be reused across multiple calls
     * of the SRF.
     */
    MemoryContext multi_call_memory_ctx;

    /*
     * OPTIONAL pointer to struct containing tuple description
     *
     * tuple_desc is for use when returning tuples (i.e., composite data types)
     * and is only needed if you are going to build the tuples with
     * heap_form_tuple() rather than with BuildTupleFromCStrings().  Note that
     * the TupleDesc pointer stored here should usually have been run through
     * BlessTupleDesc() first.
     */
    TupleDesc tuple_desc;

} FuncCallContext;

使用此基础设施的SRF要使用的宏是

SRF_IS_FIRSTCALL()

使用此项来确定您的函数是首次调用还是后续调用。仅在首次调用时，调用

SRF_FIRSTCALL_INIT()

初始化 FuncCallContext。在每次函数调用中，包括第一次调用，调用

SRF_PERCALL_SETUP()

设置使用 FuncCallContext。

如果您的函数在当前调用中有数据要返回，请使用

SRF_RETURN_NEXT(funcctx, result)

将其返回给调用者。（result 必须是 Datum 类型，可以是单个值或如上所述准备好的元组。）最后，当您的函数完成数据返回时，使用

SRF_RETURN_DONE(funcctx)

进行清理并结束SRF.

调用SRF时当前的内存上下文是一个瞬态上下文，将在调用之间清除。这意味着您不需要对所有使用 palloc 分配的内容调用 pfree；它们无论如何都会消失。但是，如果您想分配任何数据结构以在调用之间生存，则需要将它们放在其他地方。由 multi_call_memory_ctx 引用的内存上下文是需要存活到SRF运行结束的任何数据的合适位置。在大多数情况下，这意味着您应该在进行首次调用设置时切换到 multi_call_memory_ctx。使用 funcctx->user_fctx 来保存指向任何此类跨调用数据结构的指针。（您在 multi_call_memory_ctx 中分配的数据将在查询结束时自动消失，因此也不需要手动释放这些数据。）

一个完整的伪代码示例如下所示

Datum
my_set_returning_function(PG_FUNCTION_ARGS)
{
    FuncCallContext  *funcctx;
    Datum             result;
    further declarations as needed

    if (SRF_IS_FIRSTCALL())
    {
        MemoryContext oldcontext;

        funcctx = SRF_FIRSTCALL_INIT();
        oldcontext = MemoryContextSwitchTo(funcctx->multi_call_memory_ctx);
        /* One-time setup code appears here: */
        user code
        if returning composite
            build TupleDesc, and perhaps AttInMetadata
        endif returning composite
        user code
        MemoryContextSwitchTo(oldcontext);
    }

    /* Each-time setup code appears here: */
    user code
    funcctx = SRF_PERCALL_SETUP();
    user code

    /* this is just one way we might test whether we are done: */
    if (funcctx->call_cntr < funcctx->max_calls)
    {
        /* Here we want to return another item: */
        user code
        obtain result Datum
        SRF_RETURN_NEXT(funcctx, result);
    }
    else
    {
        /* Here we are done returning items, so just report that fact. */
        /* (Resist the temptation to put cleanup code here.) */
        SRF_RETURN_DONE(funcctx);
    }
}

一个简单的完整示例SRF返回复合类型看起来像

PG_FUNCTION_INFO_V1(retcomposite);

Datum
retcomposite(PG_FUNCTION_ARGS)
{
    FuncCallContext     *funcctx;
    int                  call_cntr;
    int                  max_calls;
    TupleDesc            tupdesc;
    AttInMetadata       *attinmeta;

    /* stuff done only on the first call of the function */
    if (SRF_IS_FIRSTCALL())
    {
        MemoryContext   oldcontext;

        /* create a function context for cross-call persistence */
        funcctx = SRF_FIRSTCALL_INIT();

        /* switch to memory context appropriate for multiple function calls */
        oldcontext = MemoryContextSwitchTo(funcctx->multi_call_memory_ctx);

        /* total number of tuples to be returned */
        funcctx->max_calls = PG_GETARG_INT32(0);

        /* Build a tuple descriptor for our result type */
        if (get_call_result_type(fcinfo, NULL, &tupdesc) != TYPEFUNC_COMPOSITE)
            ereport(ERROR,
                    (errcode(ERRCODE_FEATURE_NOT_SUPPORTED),
                     errmsg("function returning record called in context "
                            "that cannot accept type record")));

        /*
         * generate attribute metadata needed later to produce tuples from raw
         * C strings
         */
        attinmeta = TupleDescGetAttInMetadata(tupdesc);
        funcctx->attinmeta = attinmeta;

        MemoryContextSwitchTo(oldcontext);
    }

    /* stuff done on every call of the function */
    funcctx = SRF_PERCALL_SETUP();

    call_cntr = funcctx->call_cntr;
    max_calls = funcctx->max_calls;
    attinmeta = funcctx->attinmeta;

    if (call_cntr < max_calls)    /* do when there is more left to send */
    {
        char       **values;
        HeapTuple    tuple;
        Datum        result;

        /*
         * Prepare a values array for building the returned tuple.
         * This should be an array of C strings which will
         * be processed later by the type input functions.
         */
        values = (char **) palloc(3 * sizeof(char *));
        values[0] = (char *) palloc(16 * sizeof(char));
        values[1] = (char *) palloc(16 * sizeof(char));
        values[2] = (char *) palloc(16 * sizeof(char));

        snprintf(values[0], 16, "%d", 1 * PG_GETARG_INT32(1));
        snprintf(values[1], 16, "%d", 2 * PG_GETARG_INT32(1));
        snprintf(values[2], 16, "%d", 3 * PG_GETARG_INT32(1));

        /* build a tuple */
        tuple = BuildTupleFromCStrings(attinmeta, values);

        /* make the tuple into a datum */
        result = HeapTupleGetDatum(tuple);

        /* clean up (this is not really necessary) */
        pfree(values[0]);
        pfree(values[1]);
        pfree(values[2]);
        pfree(values);

        SRF_RETURN_NEXT(funcctx, result);
    }
    else    /* do when there is no more left */
    {
        SRF_RETURN_DONE(funcctx);
    }
}

在 SQL 中声明此函数的一种方法是

CREATE TYPE __retcomposite AS (f1 integer, f2 integer, f3 integer);

CREATE OR REPLACE FUNCTION retcomposite(integer, integer)
    RETURNS SETOF __retcomposite
    AS 'filename', 'retcomposite'
    LANGUAGE C IMMUTABLE STRICT;

另一种方法是使用 OUT 参数

CREATE OR REPLACE FUNCTION retcomposite(IN integer, IN integer,
    OUT f1 integer, OUT f2 integer, OUT f3 integer)
    RETURNS SETOF record
    AS 'filename', 'retcomposite'
    LANGUAGE C IMMUTABLE STRICT;

请注意，在这种方法中，函数的输出类型形式上是一个匿名 record 类型。

C 语言函数可以声明为接受和返回 第 36.2.5 节 中描述的多态类型。当函数的参数或返回类型定义为多态类型时，函数作者无法提前知道它将使用什么数据类型调用或需要返回什么数据类型。fmgr.h 中提供了两个例程，允许版本 1 C 函数发现其参数的实际数据类型以及预期返回的类型。这些例程称为 get_fn_expr_rettype(FmgrInfo *flinfo) 和 get_fn_expr_argtype(FmgrInfo *flinfo, int argnum)。它们返回结果或参数类型 OID，如果信息不可用，则返回 InvalidOid。结构 flinfo 通常作为 fcinfo->flinfo 访问。参数 argnum 基于零。get_call_result_type 也可以用作 get_fn_expr_rettype 的替代。还有 get_fn_expr_variadic，可用于查找可变参数是否已合并到数组中。这主要用于 VARIADIC "any" 函数，因为对于采用普通数组类型的可变函数，此类合并总是会发生。

例如，假设我们要编写一个函数，接受任何类型的单个元素，并返回该类型的一维数组

PG_FUNCTION_INFO_V1(make_array);
Datum
make_array(PG_FUNCTION_ARGS)
{
    ArrayType  *result;
    Oid         element_type = get_fn_expr_argtype(fcinfo->flinfo, 0);
    Datum       element;
    bool        isnull;
    int16       typlen;
    bool        typbyval;
    char        typalign;
    int         ndims;
    int         dims[MAXDIM];
    int         lbs[MAXDIM];

    if (!OidIsValid(element_type))
        elog(ERROR, "could not determine data type of input");

    /* get the provided element, being careful in case it's NULL */
    isnull = PG_ARGISNULL(0);
    if (isnull)
        element = (Datum) 0;
    else
        element = PG_GETARG_DATUM(0);

    /* we have one dimension */
    ndims = 1;
    /* and one element */
    dims[0] = 1;
    /* and lower bound is 1 */
    lbs[0] = 1;

    /* get required info about the element type */
    get_typlenbyvalalign(element_type, &typlen, &typbyval, &typalign);

    /* now build the array */
    result = construct_md_array(&element, &isnull, ndims, dims, lbs,
                                element_type, typlen, typbyval, typalign);

    PG_RETURN_ARRAYTYPE_P(result);
}

以下命令在 SQL 中声明函数 make_array

CREATE FUNCTION make_array(anyelement) RETURNS anyarray
    AS 'DIRECTORY/funcs', 'make_array'
    LANGUAGE C IMMUTABLE;

多态性有一种变体仅适用于 C 语言函数：它们可以声明为接受 "any" 类型的参数。（请注意，此类型名称必须用双引号引起来，因为它也是 SQL 保留字。）这与 anyelement 的工作方式类似，不同之处在于它不限制不同的 "any" 参数为同一类型，它们也无助于确定函数的返回类型。C 语言函数还可以将其最后一个参数声明为 VARIADIC "any"。这将匹配一个或多个任何类型的实际参数（不一定是相同类型）。这些参数不会像普通可变参数函数那样收集到数组中；它们将单独传递给函数。使用此功能时，必须使用 PG_NARGS() 宏和上述方法来确定实际参数的数量及其类型。此外，此类函数的用户可能希望在其函数调用中使用 VARIADIC 关键字，期望函数将数组元素视为单独的参数。如果需要此行为，函数本身必须在使用 get_fn_expr_variadic 检测到实际参数已标记为 VARIADIC 后实现此行为。

插件可以通过调用在等待事件类型 Extension 下定义自定义等待事件

uint32 WaitEventExtensionNew(const char *wait_event_name)

等待事件与面向用户的自定义字符串相关联。一个示例可以在 PostgreSQL 源代码树中的 src/test/modules/worker_spi 中找到。

自定义等待事件可在 pg_stat_activity 中查看

=# SELECT wait_event_type, wait_event FROM pg_stat_activity
     WHERE backend_type ~ 'worker_spi';
 wait_event_type |  wait_event
-----------------+---------------
 Extension       | WorkerSpiMain
(1 row)

使用宏声明具有给定 name 的注入点

INJECTION_POINT(name, arg);

服务器代码中已在战略位置声明了一些注入点。在添加新的注入点后，代码需要编译才能使该注入点在二进制文件中可用。C 语言编写的插件可以使用相同的宏在自己的代码中声明注入点。注入点名称应使用小写字符，并用连字符分隔。arg 是在运行时传递给回调的可选参数值。

执行注入点可能需要分配少量内存，这可能会失败。如果您需要在不允许动态分配的关键部分中设置注入点，可以使用以下宏进行两步操作

INJECTION_POINT_LOAD(name);
INJECTION_POINT_CACHED(name, arg);

在进入临界区之前，调用 INJECTION_POINT_LOAD。它会检查共享内存状态，如果回调处于活动状态，则将其加载到后端私有内存中。在临界区内部，使用 INJECTION_POINT_CACHED 执行回调。

插件可以通过调用将回调附加到已声明的注入点

extern void InjectionPointAttach(const char *name,
                                 const char *library,
                                 const char *function,
                                 const void *private_data,
                                 int private_data_size);

name 是注入点的名称，当执行到达时，它将执行从 library 加载的 function。private_data 是一个大小为 private_data_size 的私有数据区域，作为参数传递给执行时的回调。

这是一个 InjectionPointCallback 回调的示例

static void
custom_injection_callback(const char *name,
                          const void *private_data,
                          void *arg)
{
    uint32 wait_event_info = WaitEventInjectionPointNew(name);

    pgstat_report_wait_start(wait_event_info);
    elog(NOTICE, "%s: executed custom callback", name);
    pgstat_report_wait_end();
}

此回调将消息以 NOTICE 严重性打印到服务器错误日志中，但回调可以实现更复杂的逻辑。

定义当达到注入点时要执行的操作的另一种方法是将测试代码添加到正常源代码旁边。如果操作例如依赖于加载模块无法访问的局部变量，这会很有用。然后可以使用 IS_INJECTION_POINT_ATTACHED 宏来检查注入点是否已附加，例如

#ifdef USE_INJECTION_POINTS
if (IS_INJECTION_POINT_ATTACHED("before-foobar"))
{
    /* change a local variable if injection point is attached */
    local_var = 123;

    /* also execute the callback */
    INJECTION_POINT_CACHED("before-foobar", NULL);
}
#endif

请注意，附加到注入点的回调不会由 IS_INJECTION_POINT_ATTACHED 宏执行。如果要执行回调，您还必须像上面的示例一样调用 INJECTION_POINT_CACHED。

或者，可以通过调用分离注入点

extern bool InjectionPointDetach(const char *name);

成功时返回 true，否则返回 false。

附加到注入点的回调在所有后端都可用，包括在调用 InjectionPointAttach 之后启动的后端。它在服务器运行时或使用 InjectionPointDetach 分离注入点之前一直保持附加状态。

一个示例可以在 PostgreSQL 源代码树中的 src/test/modules/injection_points 中找到。

启用注入点需要使用 configure 时的 --enable-injection-points 或使用 Meson 时的 -Dinjection_points=true。

用 C 语言编写的插件可以使用在 累积统计系统 中注册的自定义累积统计类型。

首先，定义一个 PgStat_KindInfo，其中包含与注册的自定义类型相关的所有信息。例如

static const PgStat_KindInfo custom_stats = {
    .name = "custom_stats",
    .fixed_amount = false,
    .shared_size = sizeof(PgStatShared_Custom),
    .shared_data_off = offsetof(PgStatShared_Custom, stats),
    .shared_data_len = sizeof(((PgStatShared_Custom *) 0)->stats),
    .pending_size = sizeof(PgStat_StatCustomEntry),
}

然后，每个需要使用此自定义类型的后端都需要使用 pgstat_register_kind 和一个唯一的 ID 来注册它，该 ID 用于存储与此统计类型相关的条目

extern PgStat_Kind pgstat_register_kind(PgStat_Kind kind,
                                        const PgStat_KindInfo *kind_info);

在开发新扩展时，对 kind 使用 PGSTAT_KIND_EXPERIMENTAL。当您准备将扩展发布给用户时，请在 自定义累积统计 页面上保留一个类型 ID。

PgStat_KindInfo 的 API 详情可以在 src/include/utils/pgstat_internal.h 中找到。

注册的统计类型与一个名称和在共享内存中共享的唯一 ID 相关联。每个使用自定义统计类型的后端都维护一个本地缓存，用于存储每个自定义 PgStat_KindInfo 的信息。

将实现自定义累积统计类型的扩展模块放置在 shared_preload_libraries 中，以便在 PostgreSQL 启动期间尽早加载它。

一个描述如何注册和使用自定义统计信息的示例可以在 src/test/modules/injection_points 中找到。

尽管 PostgreSQL 后端是用 C 编写的，但如果遵循以下指导方针，则可以用 C++ 编写扩展

总而言之，最好将 C++ 代码置于 extern C 函数的屏障之后，这些函数与后端进行接口，并避免异常、内存和调用栈泄漏。