PostgreSQL Source Code git master
All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
funcapi.h
Go to the documentation of this file.
1/*-------------------------------------------------------------------------
2 *
3 * funcapi.h
4 * Definitions for functions which return composite type and/or sets
5 * or work on VARIADIC inputs.
6 *
7 * This file must be included by all Postgres modules that either define
8 * or call FUNCAPI-callable functions or macros.
9 *
10 *
11 * Copyright (c) 2002-2025, PostgreSQL Global Development Group
12 *
13 * src/include/funcapi.h
14 *
15 *-------------------------------------------------------------------------
16 */
17#ifndef FUNCAPI_H
18#define FUNCAPI_H
19
20#include "access/tupdesc.h"
21#include "executor/executor.h"
22#include "executor/tuptable.h"
23#include "fmgr.h"
24
25/*-------------------------------------------------------------------------
26 * Support to ease writing Functions returning composite types
27 *-------------------------------------------------------------------------
28 *
29 * This struct holds arrays of individual attribute information
30 * needed to create a tuple from raw C strings. It also requires
31 * a copy of the TupleDesc. The information carried here
32 * is derived from the TupleDesc, but it is stored here to
33 * avoid redundant cpu cycles on each call to an SRF.
34 */
35typedef struct AttInMetadata
36{
37 /* full TupleDesc */
39
40 /* array of attribute type input function finfo */
42
43 /* array of attribute type i/o parameter OIDs */
45
46 /* array of attribute typmod */
49
50/*-------------------------------------------------------------------------
51 * Support struct to ease writing Set Returning Functions (SRFs)
52 *-------------------------------------------------------------------------
53 *
54 * This struct holds function context for Set Returning Functions.
55 * Use fn_extra to hold a pointer to it across calls
56 */
57typedef struct FuncCallContext
58{
59 /*
60 * Number of times we've been called before
61 *
62 * call_cntr is initialized to 0 for you by SRF_FIRSTCALL_INIT(), and
63 * incremented for you every time SRF_RETURN_NEXT() is called.
64 */
66
67 /*
68 * OPTIONAL maximum number of calls
69 *
70 * max_calls is here for convenience only and setting it is optional. If
71 * not set, you must provide alternative means to know when the function
72 * is done.
73 */
75
76 /*
77 * OPTIONAL pointer to miscellaneous user-provided context information
78 *
79 * user_fctx is for use as a pointer to your own struct to retain
80 * arbitrary context information between calls of your function.
81 */
82 void *user_fctx;
83
84 /*
85 * OPTIONAL pointer to struct containing attribute type input metadata
86 *
87 * attinmeta is for use when returning tuples (i.e. composite data types)
88 * and is not used when returning base data types. It is only needed if
89 * you intend to use BuildTupleFromCStrings() to create the return tuple.
90 */
92
93 /*
94 * memory context used for structures that must live for multiple calls
95 *
96 * multi_call_memory_ctx is set by SRF_FIRSTCALL_INIT() for you, and used
97 * by SRF_RETURN_DONE() for cleanup. It is the most appropriate memory
98 * context for any memory that is to be reused across multiple calls of
99 * the SRF.
100 */
102
103 /*
104 * OPTIONAL pointer to struct containing tuple description
105 *
106 * tuple_desc is for use when returning tuples (i.e. composite data types)
107 * and is only needed if you are going to build the tuples with
108 * heap_form_tuple() rather than with BuildTupleFromCStrings(). Note that
109 * the TupleDesc pointer stored here should usually have been run through
110 * BlessTupleDesc() first.
111 */
113
115
116/*----------
117 * Support to ease writing functions returning composite types
118 *
119 * External declarations:
120 * get_call_result_type:
121 * Given a function's call info record, determine the kind of datatype
122 * it is supposed to return. If resultTypeId isn't NULL, *resultTypeId
123 * receives the actual datatype OID (this is mainly useful for scalar
124 * result types). If resultTupleDesc isn't NULL, *resultTupleDesc
125 * receives a pointer to a TupleDesc when the result is of a composite
126 * type, or NULL when it's a scalar result or the rowtype could not be
127 * determined. NB: the tupledesc should be copied if it is to be
128 * accessed over a long period.
129 * get_expr_result_type:
130 * Given an expression node, return the same info as for
131 * get_call_result_type. Note: the cases in which rowtypes cannot be
132 * determined are different from the cases for get_call_result_type.
133 * get_func_result_type:
134 * Given only a function's OID, return the same info as for
135 * get_call_result_type. Note: the cases in which rowtypes cannot be
136 * determined are different from the cases for get_call_result_type.
137 * Do *not* use this if you can use one of the others.
138 *
139 * See also get_expr_result_tupdesc(), which is a convenient wrapper around
140 * get_expr_result_type() for use when the caller only cares about
141 * determinable-rowtype cases.
142 *----------
143 */
144
145/* Type categories for get_call_result_type and siblings */
146typedef enum TypeFuncClass
147{
148 TYPEFUNC_SCALAR, /* scalar result type */
149 TYPEFUNC_COMPOSITE, /* determinable rowtype result */
150 TYPEFUNC_COMPOSITE_DOMAIN, /* domain over determinable rowtype result */
151 TYPEFUNC_RECORD, /* indeterminate rowtype result */
152 TYPEFUNC_OTHER, /* bogus type, eg pseudotype */
154
156 Oid *resultTypeId,
157 TupleDesc *resultTupleDesc);
159 Oid *resultTypeId,
160 TupleDesc *resultTupleDesc);
161extern TypeFuncClass get_func_result_type(Oid functionId,
162 Oid *resultTypeId,
163 TupleDesc *resultTupleDesc);
164
165extern TupleDesc get_expr_result_tupdesc(Node *expr, bool noError);
166
167extern bool resolve_polymorphic_argtypes(int numargs, Oid *argtypes,
168 char *argmodes,
169 Node *call_expr);
170
171extern int get_func_arg_info(HeapTuple procTup,
172 Oid **p_argtypes, char ***p_argnames,
173 char **p_argmodes);
174
175extern int get_func_input_arg_names(Datum proargnames, Datum proargmodes,
176 char ***arg_names);
177
178extern int get_func_trftypes(HeapTuple procTup, Oid **p_trftypes);
179extern char *get_func_result_name(Oid functionId);
180
182 Datum proallargtypes,
183 Datum proargmodes,
184 Datum proargnames);
186
187
188/*----------
189 * Support to ease writing functions returning composite types
190 *
191 * External declarations:
192 * TupleDesc BlessTupleDesc(TupleDesc tupdesc) - "Bless" a completed tuple
193 * descriptor so that it can be used to return properly labeled tuples.
194 * You need to call this if you are going to use heap_form_tuple directly.
195 * TupleDescGetAttInMetadata does it for you, however, so no need to call
196 * it if you call TupleDescGetAttInMetadata.
197 * AttInMetadata *TupleDescGetAttInMetadata(TupleDesc tupdesc) - Build an
198 * AttInMetadata struct based on the given TupleDesc. AttInMetadata can
199 * be used in conjunction with C strings to produce a properly formed
200 * tuple.
201 * HeapTuple BuildTupleFromCStrings(AttInMetadata *attinmeta, char **values) -
202 * build a HeapTuple given user data in C string form. values is an array
203 * of C strings, one for each attribute of the return tuple.
204 * Datum HeapTupleHeaderGetDatum(HeapTupleHeader tuple) - convert a
205 * HeapTupleHeader to a Datum.
206 *
207 * Inline declarations:
208 * HeapTupleGetDatum(HeapTuple tuple) - convert a HeapTuple to a Datum.
209 *
210 * Obsolete routines and macros:
211 * TupleDesc RelationNameGetTupleDesc(const char *relname) - Use to get a
212 * TupleDesc based on a named relation.
213 * TupleDesc TypeGetTupleDesc(Oid typeoid, List *colaliases) - Use to get a
214 * TupleDesc based on a type OID.
215 * TupleGetDatum(TupleTableSlot *slot, HeapTuple tuple) - get a Datum
216 * given a tuple and a slot.
217 *----------
218 */
219
220extern TupleDesc RelationNameGetTupleDesc(const char *relname);
221extern TupleDesc TypeGetTupleDesc(Oid typeoid, List *colaliases);
222
223/* from execTuples.c */
224extern TupleDesc BlessTupleDesc(TupleDesc tupdesc);
226extern HeapTuple BuildTupleFromCStrings(AttInMetadata *attinmeta, char **values);
228
229static inline Datum
231{
232 return HeapTupleHeaderGetDatum(tuple->t_data);
233}
234
235/* obsolete version of above */
236#define TupleGetDatum(_slot, _tuple) HeapTupleGetDatum(_tuple)
237
238
239/*----------
240 * Support for Set Returning Functions (SRFs)
241 *
242 * The basic API for SRFs using ValuePerCall mode looks something like this:
243 *
244 * Datum
245 * my_Set_Returning_Function(PG_FUNCTION_ARGS)
246 * {
247 * FuncCallContext *funcctx;
248 * Datum result;
249 * MemoryContext oldcontext;
250 * <user defined declarations>
251 *
252 * if (SRF_IS_FIRSTCALL())
253 * {
254 * funcctx = SRF_FIRSTCALL_INIT();
255 * // switch context when allocating stuff to be used in later calls
256 * oldcontext = MemoryContextSwitchTo(funcctx->multi_call_memory_ctx);
257 * <user defined code>
258 * <if returning composite>
259 * <build TupleDesc, and perhaps AttInMetadata>
260 * <endif returning composite>
261 * <user defined code>
262 * // return to original context when allocating transient memory
263 * MemoryContextSwitchTo(oldcontext);
264 * }
265 * <user defined code>
266 * funcctx = SRF_PERCALL_SETUP();
267 * <user defined code>
268 *
269 * if (funcctx->call_cntr < funcctx->max_calls)
270 * {
271 * <user defined code>
272 * <obtain result Datum>
273 * SRF_RETURN_NEXT(funcctx, result);
274 * }
275 * else
276 * SRF_RETURN_DONE(funcctx);
277 * }
278 *
279 * NOTE: there is no guarantee that a SRF using ValuePerCall mode will be
280 * run to completion; for example, a query with LIMIT might stop short of
281 * fetching all the rows. Therefore, do not expect that you can do resource
282 * cleanup just before SRF_RETURN_DONE(). You need not worry about releasing
283 * memory allocated in multi_call_memory_ctx, but holding file descriptors or
284 * other non-memory resources open across calls is a bug. SRFs that need
285 * such resources should not use these macros, but instead populate a
286 * tuplestore during a single call, as set up by InitMaterializedSRF() (see
287 * fmgr/README). Alternatively, set up a callback to release resources
288 * at query shutdown, using RegisterExprContextCallback().
289 *
290 *----------
291 */
292
293/* from funcapi.c */
294
295/* flag bits for InitMaterializedSRF() */
296#define MAT_SRF_USE_EXPECTED_DESC 0x01 /* use expectedDesc as tupdesc. */
297#define MAT_SRF_BLESS 0x02 /* "Bless" a tuple descriptor with
298 * BlessTupleDesc(). */
299extern void InitMaterializedSRF(FunctionCallInfo fcinfo, bits32 flags);
300
305#define SRF_IS_FIRSTCALL() (fcinfo->flinfo->fn_extra == NULL)
307#define SRF_FIRSTCALL_INIT() init_MultiFuncCall(fcinfo)
309#define SRF_PERCALL_SETUP() per_MultiFuncCall(fcinfo)
311#define SRF_RETURN_NEXT(_funcctx, _result) \
312 do { \
313 ReturnSetInfo *rsi; \
314 (_funcctx)->call_cntr++; \
315 rsi = (ReturnSetInfo *) fcinfo->resultinfo; \
316 rsi->isDone = ExprMultipleResult; \
317 PG_RETURN_DATUM(_result); \
318 } while (0)
320#define SRF_RETURN_NEXT_NULL(_funcctx) \
321 do { \
322 ReturnSetInfo *rsi; \
323 (_funcctx)->call_cntr++; \
324 rsi = (ReturnSetInfo *) fcinfo->resultinfo; \
325 rsi->isDone = ExprMultipleResult; \
326 PG_RETURN_NULL(); \
327 } while (0)
329#define SRF_RETURN_DONE(_funcctx) \
330 do { \
331 ReturnSetInfo *rsi; \
332 end_MultiFuncCall(fcinfo, _funcctx); \
333 rsi = (ReturnSetInfo *) fcinfo->resultinfo; \
334 rsi->isDone = ExprEndResult; \
335 PG_RETURN_NULL(); \
336 } while (0)
337
338/*----------
339 * Support to ease writing of functions dealing with VARIADIC inputs
340 *----------
341 *
342 * This function extracts a set of argument values, types and NULL markers
343 * for a given input function. This returns a set of data:
344 * - **values includes the set of Datum values extracted.
345 * - **types the data type OID for each element.
346 * - **nulls tracks if an element is NULL.
347 *
348 * variadic_start indicates the argument number where the VARIADIC argument
349 * starts.
350 * convert_unknown set to true will enforce the conversion of arguments
351 * with unknown data type to text.
352 *
353 * The return result is the number of elements stored, or -1 in the case of
354 * "VARIADIC NULL".
355 */
356extern int extract_variadic_args(FunctionCallInfo fcinfo, int variadic_start,
357 bool convert_unknown, Datum **args,
358 Oid **types, bool **nulls);
359
360#endif /* FUNCAPI_H */
static Datum values[MAXATTR]
Definition: bootstrap.c:151
uint32 bits32
Definition: c.h:511
int32_t int32
Definition: c.h:498
uint64_t uint64
Definition: c.h:503
struct typedefs * types
Definition: ecpg.c:30
#define PG_FUNCTION_ARGS
Definition: fmgr.h:193
TupleDesc BlessTupleDesc(TupleDesc tupdesc)
Definition: execTuples.c:2260
void InitMaterializedSRF(FunctionCallInfo fcinfo, bits32 flags)
Definition: funcapi.c:76
HeapTuple BuildTupleFromCStrings(AttInMetadata *attinmeta, char **values)
Definition: execTuples.c:2324
int get_func_trftypes(HeapTuple procTup, Oid **p_trftypes)
Definition: funcapi.c:1475
TypeFuncClass
Definition: funcapi.h:147
@ TYPEFUNC_SCALAR
Definition: funcapi.h:148
@ TYPEFUNC_COMPOSITE
Definition: funcapi.h:149
@ TYPEFUNC_RECORD
Definition: funcapi.h:151
@ TYPEFUNC_COMPOSITE_DOMAIN
Definition: funcapi.h:150
@ TYPEFUNC_OTHER
Definition: funcapi.h:152
struct AttInMetadata AttInMetadata
TupleDesc build_function_result_tupdesc_t(HeapTuple procTuple)
Definition: funcapi.c:1705
char * get_func_result_name(Oid functionId)
Definition: funcapi.c:1607
TupleDesc build_function_result_tupdesc_d(char prokind, Datum proallargtypes, Datum proargmodes, Datum proargnames)
Definition: funcapi.c:1751
Datum HeapTupleHeaderGetDatum(HeapTupleHeader tuple)
Definition: execTuples.c:2413
bool resolve_polymorphic_argtypes(int numargs, Oid *argtypes, char *argmodes, Node *call_expr)
Definition: funcapi.c:1064
struct FuncCallContext FuncCallContext
void end_MultiFuncCall(PG_FUNCTION_ARGS, FuncCallContext *funcctx)
Definition: funcapi.c:220
int get_func_input_arg_names(Datum proargnames, Datum proargmodes, char ***arg_names)
Definition: funcapi.c:1522
int get_func_arg_info(HeapTuple procTup, Oid **p_argtypes, char ***p_argnames, char **p_argmodes)
Definition: funcapi.c:1379
FuncCallContext * per_MultiFuncCall(PG_FUNCTION_ARGS)
Definition: funcapi.c:208
FuncCallContext * init_MultiFuncCall(PG_FUNCTION_ARGS)
Definition: funcapi.c:133
TupleDesc RelationNameGetTupleDesc(const char *relname)
Definition: funcapi.c:1870
TypeFuncClass get_call_result_type(FunctionCallInfo fcinfo, Oid *resultTypeId, TupleDesc *resultTupleDesc)
Definition: funcapi.c:276
static Datum HeapTupleGetDatum(const HeapTupleData *tuple)
Definition: funcapi.h:230
int extract_variadic_args(FunctionCallInfo fcinfo, int variadic_start, bool convert_unknown, Datum **args, Oid **types, bool **nulls)
Definition: funcapi.c:2005
TupleDesc get_expr_result_tupdesc(Node *expr, bool noError)
Definition: funcapi.c:551
AttInMetadata * TupleDescGetAttInMetadata(TupleDesc tupdesc)
Definition: execTuples.c:2275
TupleDesc TypeGetTupleDesc(Oid typeoid, List *colaliases)
Definition: funcapi.c:1903
TypeFuncClass get_func_result_type(Oid functionId, Oid *resultTypeId, TupleDesc *resultTupleDesc)
Definition: funcapi.c:410
TypeFuncClass get_expr_result_type(Node *expr, Oid *resultTypeId, TupleDesc *resultTupleDesc)
Definition: funcapi.c:299
NameData relname
Definition: pg_class.h:38
uintptr_t Datum
Definition: postgres.h:69
unsigned int Oid
Definition: postgres_ext.h:30
FmgrInfo * attinfuncs
Definition: funcapi.h:41
TupleDesc tupdesc
Definition: funcapi.h:38
Oid * attioparams
Definition: funcapi.h:44
int32 * atttypmods
Definition: funcapi.h:47
Definition: fmgr.h:57
void * user_fctx
Definition: funcapi.h:82
uint64 max_calls
Definition: funcapi.h:74
uint64 call_cntr
Definition: funcapi.h:65
AttInMetadata * attinmeta
Definition: funcapi.h:91
MemoryContext multi_call_memory_ctx
Definition: funcapi.h:101
TupleDesc tuple_desc
Definition: funcapi.h:112
HeapTupleHeader t_data
Definition: htup.h:68
Definition: pg_list.h:54
Definition: nodes.h:135