Age Owner Branch data TLA Line data Source code
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-2024, 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 : : */
35 : : typedef struct AttInMetadata
36 : : {
37 : : /* full TupleDesc */
38 : : TupleDesc tupdesc;
39 : :
40 : : /* array of attribute type input function finfo */
41 : : FmgrInfo *attinfuncs;
42 : :
43 : : /* array of attribute type i/o parameter OIDs */
44 : : Oid *attioparams;
45 : :
46 : : /* array of attribute typmod */
47 : : int32 *atttypmods;
48 : : } AttInMetadata;
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 : : */
57 : : typedef 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 : : */
65 : : uint64 call_cntr;
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 : : */
74 : : uint64 max_calls;
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 : : */
91 : : AttInMetadata *attinmeta;
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 : : */
101 : : MemoryContext multi_call_memory_ctx;
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 : : */
112 : : TupleDesc tuple_desc;
113 : :
114 : : } FuncCallContext;
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 */
146 : : typedef 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 */
153 : : } TypeFuncClass;
154 : :
155 : : extern TypeFuncClass get_call_result_type(FunctionCallInfo fcinfo,
156 : : Oid *resultTypeId,
157 : : TupleDesc *resultTupleDesc);
158 : : extern TypeFuncClass get_expr_result_type(Node *expr,
159 : : Oid *resultTypeId,
160 : : TupleDesc *resultTupleDesc);
161 : : extern TypeFuncClass get_func_result_type(Oid functionId,
162 : : Oid *resultTypeId,
163 : : TupleDesc *resultTupleDesc);
164 : :
165 : : extern TupleDesc get_expr_result_tupdesc(Node *expr, bool noError);
166 : :
167 : : extern bool resolve_polymorphic_argtypes(int numargs, Oid *argtypes,
168 : : char *argmodes,
169 : : Node *call_expr);
170 : :
171 : : extern int get_func_arg_info(HeapTuple procTup,
172 : : Oid **p_argtypes, char ***p_argnames,
173 : : char **p_argmodes);
174 : :
175 : : extern int get_func_input_arg_names(Datum proargnames, Datum proargmodes,
176 : : char ***arg_names);
177 : :
178 : : extern int get_func_trftypes(HeapTuple procTup, Oid **p_trftypes);
179 : : extern char *get_func_result_name(Oid functionId);
180 : :
181 : : extern TupleDesc build_function_result_tupdesc_d(char prokind,
182 : : Datum proallargtypes,
183 : : Datum proargmodes,
184 : : Datum proargnames);
185 : : extern TupleDesc build_function_result_tupdesc_t(HeapTuple procTuple);
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 : :
220 : : extern TupleDesc RelationNameGetTupleDesc(const char *relname);
221 : : extern TupleDesc TypeGetTupleDesc(Oid typeoid, List *colaliases);
222 : :
223 : : /* from execTuples.c */
224 : : extern TupleDesc BlessTupleDesc(TupleDesc tupdesc);
225 : : extern AttInMetadata *TupleDescGetAttInMetadata(TupleDesc tupdesc);
226 : : extern HeapTuple BuildTupleFromCStrings(AttInMetadata *attinmeta, char **values);
227 : : extern Datum HeapTupleHeaderGetDatum(HeapTupleHeader tuple);
228 : :
229 : : static inline Datum
565 peter@eisentraut.org 230 :CBC 818384 : HeapTupleGetDatum(const HeapTupleData *tuple)
231 : : {
232 : 818384 : 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(). */
299 : : extern void InitMaterializedSRF(FunctionCallInfo fcinfo, bits32 flags);
300 : :
301 : : extern FuncCallContext *init_MultiFuncCall(PG_FUNCTION_ARGS);
302 : : extern FuncCallContext *per_MultiFuncCall(PG_FUNCTION_ARGS);
303 : : extern void end_MultiFuncCall(PG_FUNCTION_ARGS, FuncCallContext *funcctx);
304 : :
305 : : #define SRF_IS_FIRSTCALL() (fcinfo->flinfo->fn_extra == NULL)
306 : :
307 : : #define SRF_FIRSTCALL_INIT() init_MultiFuncCall(fcinfo)
308 : :
309 : : #define SRF_PERCALL_SETUP() per_MultiFuncCall(fcinfo)
310 : :
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)
319 : :
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)
328 : :
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 : : */
356 : : extern 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 */
|
