PostgreSQL Source Code  git master
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-2019, PostgreSQL Global Development Group
12  *
13  * src/include/funcapi.h
14  *
15  *-------------------------------------------------------------------------
16  */
17 #ifndef FUNCAPI_H
18 #define FUNCAPI_H
19 
20 #include "fmgr.h"
21 #include "access/tupdesc.h"
22 #include "executor/executor.h"
23 #include "executor/tuptable.h"
24 
25 
26 /*-------------------------------------------------------------------------
27  * Support to ease writing Functions returning composite types
28  *-------------------------------------------------------------------------
29  *
30  * This struct holds arrays of individual attribute information
31  * needed to create a tuple from raw C strings. It also requires
32  * a copy of the TupleDesc. The information carried here
33  * is derived from the TupleDesc, but it is stored here to
34  * avoid redundant cpu cycles on each call to an SRF.
35  */
36 typedef struct AttInMetadata
37 {
38  /* full TupleDesc */
40 
41  /* array of attribute type input function finfo */
43 
44  /* array of attribute type i/o parameter OIDs */
46 
47  /* array of attribute typmod */
50 
51 /*-------------------------------------------------------------------------
52  * Support struct to ease writing Set Returning Functions (SRFs)
53  *-------------------------------------------------------------------------
54  *
55  * This struct holds function context for Set Returning Functions.
56  * Use fn_extra to hold a pointer to it across calls
57  */
58 typedef struct FuncCallContext
59 {
60  /*
61  * Number of times we've been called before
62  *
63  * call_cntr is initialized to 0 for you by SRF_FIRSTCALL_INIT(), and
64  * incremented for you every time SRF_RETURN_NEXT() is called.
65  */
66  uint64 call_cntr;
67 
68  /*
69  * OPTIONAL maximum number of calls
70  *
71  * max_calls is here for convenience only and setting it is optional. If
72  * not set, you must provide alternative means to know when the function
73  * is done.
74  */
75  uint64 max_calls;
76 
77  /*
78  * OPTIONAL pointer to miscellaneous user-provided context information
79  *
80  * user_fctx is for use as a pointer to your own struct to retain
81  * arbitrary context information between calls of your function.
82  */
83  void *user_fctx;
84 
85  /*
86  * OPTIONAL pointer to struct containing attribute type input metadata
87  *
88  * attinmeta is for use when returning tuples (i.e. composite data types)
89  * and is not used when returning base data types. It is only needed if
90  * you intend to use BuildTupleFromCStrings() to create the return tuple.
91  */
93 
94  /*
95  * memory context used for structures that must live for multiple calls
96  *
97  * multi_call_memory_ctx is set by SRF_FIRSTCALL_INIT() for you, and used
98  * by SRF_RETURN_DONE() for cleanup. It is the most appropriate memory
99  * context for any memory that is to be reused across multiple calls of
100  * the SRF.
101  */
103 
104  /*
105  * OPTIONAL pointer to struct containing tuple description
106  *
107  * tuple_desc is for use when returning tuples (i.e. composite data types)
108  * and is only needed if you are going to build the tuples with
109  * heap_form_tuple() rather than with BuildTupleFromCStrings(). Note that
110  * the TupleDesc pointer stored here should usually have been run through
111  * BlessTupleDesc() first.
112  */
114 
116 
117 /*----------
118  * Support to ease writing functions returning composite types
119  *
120  * External declarations:
121  * get_call_result_type:
122  * Given a function's call info record, determine the kind of datatype
123  * it is supposed to return. If resultTypeId isn't NULL, *resultTypeId
124  * receives the actual datatype OID (this is mainly useful for scalar
125  * result types). If resultTupleDesc isn't NULL, *resultTupleDesc
126  * receives a pointer to a TupleDesc when the result is of a composite
127  * type, or NULL when it's a scalar result or the rowtype could not be
128  * determined. NB: the tupledesc should be copied if it is to be
129  * accessed over a long period.
130  * get_expr_result_type:
131  * Given an expression node, return the same info as for
132  * get_call_result_type. Note: the cases in which rowtypes cannot be
133  * determined are different from the cases for get_call_result_type.
134  * get_func_result_type:
135  * Given only a function's OID, return the same info as for
136  * get_call_result_type. Note: the cases in which rowtypes cannot be
137  * determined are different from the cases for get_call_result_type.
138  * Do *not* use this if you can use one of the others.
139  *
140  * See also get_expr_result_tupdesc(), which is a convenient wrapper around
141  * get_expr_result_type() for use when the caller only cares about
142  * determinable-rowtype cases.
143  *----------
144  */
145 
146 /* Type categories for get_call_result_type and siblings */
147 typedef enum TypeFuncClass
148 {
149  TYPEFUNC_SCALAR, /* scalar result type */
150  TYPEFUNC_COMPOSITE, /* determinable rowtype result */
151  TYPEFUNC_COMPOSITE_DOMAIN, /* domain over determinable rowtype result */
152  TYPEFUNC_RECORD, /* indeterminate rowtype result */
153  TYPEFUNC_OTHER /* bogus type, eg pseudotype */
154 } TypeFuncClass;
155 
157  Oid *resultTypeId,
158  TupleDesc *resultTupleDesc);
160  Oid *resultTypeId,
161  TupleDesc *resultTupleDesc);
162 extern TypeFuncClass get_func_result_type(Oid functionId,
163  Oid *resultTypeId,
164  TupleDesc *resultTupleDesc);
165 
166 extern TupleDesc get_expr_result_tupdesc(Node *expr, bool noError);
167 
168 extern bool resolve_polymorphic_argtypes(int numargs, Oid *argtypes,
169  char *argmodes,
170  Node *call_expr);
171 
172 extern int get_func_arg_info(HeapTuple procTup,
173  Oid **p_argtypes, char ***p_argnames,
174  char **p_argmodes);
175 
176 extern int get_func_input_arg_names(Datum proargnames, Datum proargmodes,
177  char ***arg_names);
178 
179 extern int get_func_trftypes(HeapTuple procTup, Oid **p_trftypes);
180 extern char *get_func_result_name(Oid functionId);
181 
182 extern TupleDesc build_function_result_tupdesc_d(char prokind,
183  Datum proallargtypes,
184  Datum proargmodes,
185  Datum proargnames);
187 
188 
189 /*----------
190  * Support to ease writing functions returning composite types
191  *
192  * External declarations:
193  * TupleDesc BlessTupleDesc(TupleDesc tupdesc) - "Bless" a completed tuple
194  * descriptor so that it can be used to return properly labeled tuples.
195  * You need to call this if you are going to use heap_form_tuple directly.
196  * TupleDescGetAttInMetadata does it for you, however, so no need to call
197  * it if you call TupleDescGetAttInMetadata.
198  * AttInMetadata *TupleDescGetAttInMetadata(TupleDesc tupdesc) - Build an
199  * AttInMetadata struct based on the given TupleDesc. AttInMetadata can
200  * be used in conjunction with C strings to produce a properly formed
201  * tuple.
202  * HeapTuple BuildTupleFromCStrings(AttInMetadata *attinmeta, char **values) -
203  * build a HeapTuple given user data in C string form. values is an array
204  * of C strings, one for each attribute of the return tuple.
205  * Datum HeapTupleHeaderGetDatum(HeapTupleHeader tuple) - convert a
206  * HeapTupleHeader to a Datum.
207  *
208  * Macro declarations:
209  * HeapTupleGetDatum(HeapTuple tuple) - convert a HeapTuple to a Datum.
210  *
211  * Obsolete routines and macros:
212  * TupleDesc RelationNameGetTupleDesc(const char *relname) - Use to get a
213  * TupleDesc based on a named relation.
214  * TupleDesc TypeGetTupleDesc(Oid typeoid, List *colaliases) - Use to get a
215  * TupleDesc based on a type OID.
216  * TupleGetDatum(TupleTableSlot *slot, HeapTuple tuple) - get a Datum
217  * given a tuple and a slot.
218  *----------
219  */
220 
221 #define HeapTupleGetDatum(tuple) HeapTupleHeaderGetDatum((tuple)->t_data)
222 /* obsolete version of above */
223 #define TupleGetDatum(_slot, _tuple) HeapTupleGetDatum(_tuple)
224 
225 extern TupleDesc RelationNameGetTupleDesc(const char *relname);
226 extern TupleDesc TypeGetTupleDesc(Oid typeoid, List *colaliases);
227 
228 /* from execTuples.c */
231 extern HeapTuple BuildTupleFromCStrings(AttInMetadata *attinmeta, char **values);
233 
234 
235 /*----------
236  * Support for Set Returning Functions (SRFs)
237  *
238  * The basic API for SRFs looks something like:
239  *
240  * Datum
241  * my_Set_Returning_Function(PG_FUNCTION_ARGS)
242  * {
243  * FuncCallContext *funcctx;
244  * Datum result;
245  * MemoryContext oldcontext;
246  * <user defined declarations>
247  *
248  * if (SRF_IS_FIRSTCALL())
249  * {
250  * funcctx = SRF_FIRSTCALL_INIT();
251  * // switch context when allocating stuff to be used in later calls
252  * oldcontext = MemoryContextSwitchTo(funcctx->multi_call_memory_ctx);
253  * <user defined code>
254  * <if returning composite>
255  * <build TupleDesc, and perhaps AttInMetadata>
256  * <endif returning composite>
257  * <user defined code>
258  * // return to original context when allocating transient memory
259  * MemoryContextSwitchTo(oldcontext);
260  * }
261  * <user defined code>
262  * funcctx = SRF_PERCALL_SETUP();
263  * <user defined code>
264  *
265  * if (funcctx->call_cntr < funcctx->max_calls)
266  * {
267  * <user defined code>
268  * <obtain result Datum>
269  * SRF_RETURN_NEXT(funcctx, result);
270  * }
271  * else
272  * SRF_RETURN_DONE(funcctx);
273  * }
274  *
275  *----------
276  */
277 
278 /* from funcapi.c */
281 extern void end_MultiFuncCall(PG_FUNCTION_ARGS, FuncCallContext *funcctx);
282 
283 #define SRF_IS_FIRSTCALL() (fcinfo->flinfo->fn_extra == NULL)
284 
285 #define SRF_FIRSTCALL_INIT() init_MultiFuncCall(fcinfo)
286 
287 #define SRF_PERCALL_SETUP() per_MultiFuncCall(fcinfo)
288 
289 #define SRF_RETURN_NEXT(_funcctx, _result) \
290  do { \
291  ReturnSetInfo *rsi; \
292  (_funcctx)->call_cntr++; \
293  rsi = (ReturnSetInfo *) fcinfo->resultinfo; \
294  rsi->isDone = ExprMultipleResult; \
295  PG_RETURN_DATUM(_result); \
296  } while (0)
297 
298 #define SRF_RETURN_NEXT_NULL(_funcctx) \
299  do { \
300  ReturnSetInfo *rsi; \
301  (_funcctx)->call_cntr++; \
302  rsi = (ReturnSetInfo *) fcinfo->resultinfo; \
303  rsi->isDone = ExprMultipleResult; \
304  PG_RETURN_NULL(); \
305  } while (0)
306 
307 #define SRF_RETURN_DONE(_funcctx) \
308  do { \
309  ReturnSetInfo *rsi; \
310  end_MultiFuncCall(fcinfo, _funcctx); \
311  rsi = (ReturnSetInfo *) fcinfo->resultinfo; \
312  rsi->isDone = ExprEndResult; \
313  PG_RETURN_NULL(); \
314  } while (0)
315 
316 /*----------
317  * Support to ease writing of functions dealing with VARIADIC inputs
318  *----------
319  *
320  * This function extracts a set of argument values, types and NULL markers
321  * for a given input function. This returns a set of data:
322  * - **values includes the set of Datum values extracted.
323  * - **types the data type OID for each element.
324  * - **nulls tracks if an element is NULL.
325  *
326  * variadic_start indicates the argument number where the VARIADIC argument
327  * starts.
328  * convert_unknown set to true will enforce the conversion of arguments
329  * with unknown data type to text.
330  *
331  * The return result is the number of elements stored, or -1 in the case of
332  * "VARIADIC NULL".
333  */
334 extern int extract_variadic_args(FunctionCallInfo fcinfo, int variadic_start,
335  bool convert_unknown, Datum **values,
336  Oid **types, bool **nulls);
337 
338 #endif /* FUNCAPI_H */
uint64 call_cntr
Definition: funcapi.h:66
Definition: fmgr.h:56
Datum HeapTupleHeaderGetDatum(HeapTupleHeader tuple)
Definition: execTuples.c:2205
struct typedefs * types
Definition: ecpg.c:29
int get_func_trftypes(HeapTuple procTup, Oid **p_trftypes)
Definition: funcapi.c:957
TupleDesc build_function_result_tupdesc_t(HeapTuple procTuple)
Definition: funcapi.c:1193
TupleDesc get_expr_result_tupdesc(Node *expr, bool noError)
Definition: funcapi.c:429
TypeFuncClass get_call_result_type(FunctionCallInfo fcinfo, Oid *resultTypeId, TupleDesc *resultTupleDesc)
Definition: funcapi.c:196
Definition: nodes.h:525
TupleDesc build_function_result_tupdesc_d(char prokind, Datum proallargtypes, Datum proargmodes, Datum proargnames)
Definition: funcapi.c:1243
int32 * atttypmods
Definition: funcapi.h:48
int get_func_arg_info(HeapTuple procTup, Oid **p_argtypes, char ***p_argnames, char **p_argmodes)
Definition: funcapi.c:863
NameData relname
Definition: pg_class.h:35
unsigned int Oid
Definition: postgres_ext.h:31
Oid * attioparams
Definition: funcapi.h:45
TupleDesc tuple_desc
Definition: funcapi.h:113
signed int int32
Definition: c.h:347
int get_func_input_arg_names(Datum proargnames, Datum proargmodes, char ***arg_names)
Definition: funcapi.c:1005
TupleDesc TypeGetTupleDesc(Oid typeoid, List *colaliases)
Definition: funcapi.c:1394
TupleDesc RelationNameGetTupleDesc(const char *relname)
Definition: funcapi.c:1361
AttInMetadata * attinmeta
Definition: funcapi.h:92
TupleDesc tupdesc
Definition: funcapi.h:39
struct FuncCallContext FuncCallContext
TypeFuncClass
Definition: funcapi.h:147
void end_MultiFuncCall(PG_FUNCTION_ARGS, FuncCallContext *funcctx)
Definition: funcapi.c:140
FuncCallContext * init_MultiFuncCall(PG_FUNCTION_ARGS)
Definition: funcapi.c:53
struct AttInMetadata AttInMetadata
uintptr_t Datum
Definition: postgres.h:367
TypeFuncClass get_expr_result_type(Node *expr, Oid *resultTypeId, TupleDesc *resultTupleDesc)
Definition: funcapi.c:212
TypeFuncClass get_func_result_type(Oid functionId, Oid *resultTypeId, TupleDesc *resultTupleDesc)
Definition: funcapi.c:289
TupleDesc BlessTupleDesc(TupleDesc tupdesc)
Definition: execTuples.c:2052
MemoryContext multi_call_memory_ctx
Definition: funcapi.h:102
char * get_func_result_name(Oid functionId)
Definition: funcapi.c:1090
FuncCallContext * per_MultiFuncCall(PG_FUNCTION_ARGS)
Definition: funcapi.c:128
AttInMetadata * TupleDescGetAttInMetadata(TupleDesc tupdesc)
Definition: execTuples.c:2067
static Datum values[MAXATTR]
Definition: bootstrap.c:167
void * user_fctx
Definition: funcapi.h:83
bool resolve_polymorphic_argtypes(int numargs, Oid *argtypes, char *argmodes, Node *call_expr)
Definition: funcapi.c:661
#define PG_FUNCTION_ARGS
Definition: fmgr.h:188
HeapTuple BuildTupleFromCStrings(AttInMetadata *attinmeta, char **values)
Definition: execTuples.c:2116
FmgrInfo * attinfuncs
Definition: funcapi.h:42
int extract_variadic_args(FunctionCallInfo fcinfo, int variadic_start, bool convert_unknown, Datum **values, Oid **types, bool **nulls)
Definition: funcapi.c:1496
Definition: pg_list.h:50
uint64 max_calls
Definition: funcapi.h:75