还有一个特殊的API用于提供从C语言函数中返回集合(多行)。

一个返回集合的函数必须遵循版本-1的调用方式。

同样，源代码必须包含funcapi.h，就像上面说的那样。

一个返回集合的函数(SRF)通常为它返回的每个项都调用一次。

因此SRF必须保存足够的状态用于记住它正在做的事情以及在每次调用的时候返回下一个项。

表函数 API 提供了FuncCallContext结构用于帮助控制这个过程。

fcinfo->flinfo->fn_extra

用于保存一个跨越多次调用的指向FuncCallContext的指针。typedef struct

{

/*

* 前面已经被调用的次数

* 初始的时候，call_cntr 被 SRF_FIRSTCALL_INIT() 置为 0，

*并且每次你调用 SRF_RETURN_NEXT() 的时候都递增

*/

uint32 call_cntr;

/*

* 可选的最大调用数量

* 这里的 max_calls 只是为了方便，设置它也是可选的。

* 如果没有设置，你必须提供可选的方法来知道函数何时结束。

*/

uint32 max_calls;

/*

* 指向结果槽位的可选指针

* 这个数据类型已经过时，只用于向下兼容。也就是那些使用已废弃的TupleDescGetSlot()的用户定义 SRF

*/

TupleTableSlot *slot;

/*

* 可选的指向用户提供的杂项环境信息的指针

* user_fctx 用做一个指向你自己的结构的指针，包含任意提供给你的函数的调用间的环境信息

*/

void *user_fctx;

/*

* 可选的指向包含属性类型输入元信息的结构数组的指针

* attinmeta 用于在返回行的时候(也就是说返回复合数据类型)

* 在只返回基本(也就是标量)数据类型的时候并不需要。

* 只有在你准备用 BuildTupleFromCStrings() 创建返回行的时候才需要它。

*/

AttInMetadata *attinmeta;

/*

* 用于必须在多次调用间存活的结构的内存环境

* multi_call_memory_ctx 是由 SRF_FIRSTCALL_INIT() 为你设置的，并且由 SRF_RETURN_DONE() 用于清理。

* 它是用于存放任何需要跨越多次调用 SRF 之间重复使用的内存。

*/

MemoryContext multi_call_memory_ctx;

/*

* 可选的指针，指向包含行描述的结构

* tuple_desc 用于返回行(也就是说复合数据类型)并且只是在你想使用 heap_form_tuple() 而不是 BuildTupleFromCStrings() 制作行的时候需要。

* 请注意这里存储的 TupleDesc 指针通常应该先用 BlessTupleDesc() 处理。

*/

TupleDesc tuple_desc;

} FuncCallContext;

一个SRF使用自动操作FuncCallContext结构

(可以通过fn_extra找到)的若干个函数和宏。使用：SRF_IS_FIRSTCALL()

来判断你的函数是第一次调用还是后继的调用。只有在第一次调用的时候，使用：SRF_FIRSTCALL_INIT()

初始化FuncCallContext。在每次函数调用时(包括第一次)，使用：SRF_PERCALL_SETUP()

为使用FuncCallContext做恰当的设置以及清理任何前面的轮回里面剩下的已返回的数据。

如果你的函数有数据要返回，使用:SRF_RETURN_NEXT(funcctx, result)

返回给调用者(result必须是个Datum，要么是单个值，

要么是像前面介绍的那样准备的行)。

最后，如果你的函数结束了数据返回，使用:SRF_RETURN_DONE(funcctx)

清理并结束SRF。

在SRF被调用时的内存环境是一个临时环境，

在调用之间将会被清理掉。

这意味着你不需要pfree所有你palloc的东西；它会自动消失的。

不过，如果你想分配任何跨越调用存在的数据结构，

那你就需要把它们放在其它什么地方。

被multi_call_memory_ctx引用的环境适合用于保存那些需要直到

SRF结束前都存活的数据。在大多数情况下，

这意味着你在第一次调用设置的时候应该切换到multi_call_memory_ctx。

一个完整的伪代码例子看起来像下面这样：Datum

my_set_returning_function(PG_FUNCTION_ARGS)

{

FuncCallContext *funcctx;

Datum result;

更多的声明

if (SRF_IS_FIRSTCALL())

{

MemoryContext oldcontext;

funcctx = SRF_FIRSTCALL_INIT();

oldcontext = MemoryContextSwitchTo(funcctx->multi_call_memory_ctx);

/* 这里放出现一次的设置代码: */

用户代码

if 返回复合

制作 TupleDesc 以及可能还有 AttInMetadata

endif 返回复合

用户定义代码

MemoryContextSwitchTo(oldcontext);

}

/* 每次都执行的设置代码在这里出现: */

用户定义代码

funcctx = SRF_PERCALL_SETUP();

用户定义代码

/* 这里只是用来测试是否完成的一个方法: */

if (funcctx->call_cntr < funcctx->max_calls)

{

/* 这里想返回另外一个条目: */

用户代码

获取结果

SRF_RETURN_NEXT(funcctx, result);

}

else

{

/* 这里完成返回条目的工作了，只需要清理就OK了: */

用户代码

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;

/* 只是在第一次调用函数的时候干的事情 */

if (SRF_IS_FIRSTCALL())

{

MemoryContext oldcontext;

/* 创建一个函数环境，用于在调用间保持住 */

funcctx = SRF_FIRSTCALL_INIT();

/* 切换到适合多次函数调用的内存环境 */

oldcontext = MemoryContextSwitchTo(funcctx->multi_call_memory_ctx);

/* 要返回的行总数 */

funcctx->max_calls = PG_GETARG_UINT32(0);

/* 为了结果类型制作一个行描述 */

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")));

/*

* 生成稍后从裸 C 字符串生成行的属性元数据

*/

attinmeta = TupleDescGetAttInMetadata(tupdesc);

funcctx->attinmeta = attinmeta;

MemoryContextSwitchTo(oldcontext);

}

/* 每次函数调用都要做的事情 */

funcctx = SRF_PERCALL_SETUP();

call_cntr = funcctx->call_cntr;

max_calls = funcctx->max_calls;

attinmeta = funcctx->attinmeta;

if (call_cntr < max_calls) /* 在还有需要发送的东西时继续处理 */

{

char **values;

HeapTuple tuple;

Datum result;

/*

* 准备一个数值数组用于版本的返回行

* 它应该是一个C字符串数组，稍后可以被合适的类型输入函数处理。

*/

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));

/* 制作一个行 */

tuple = BuildTupleFromCStrings(attinmeta, values);

/* 把行做成 datum */

result = HeapTupleGetDatum(tuple);

/* 清理(这些实际上并非必要) */

pfree(values[0]);

pfree(values[1]);

pfree(values[2]);

pfree(values);

SRF_RETURN_NEXT(funcctx, result);

}

else /* 在没有数据残留的时候干的事情 */

{

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类型。

参阅源码发布包里的contrib/tablefunc

获取更多有关返回集合的函数的例子。