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-2018, 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 result slot
79  *
80  * This is obsolete and only present for backwards compatibility, viz,
81  * user-defined SRFs that use the deprecated TupleDescGetSlot().
82  */
84 
85  /*
86  * OPTIONAL pointer to miscellaneous user-provided context information
87  *
88  * user_fctx is for use as a pointer to your own struct to retain
89  * arbitrary context information between calls of your function.
90  */
91  void *user_fctx;
92 
93  /*
94  * OPTIONAL pointer to struct containing attribute type input metadata
95  *
96  * attinmeta is for use when returning tuples (i.e. composite data types)
97  * and is not used when returning base data types. It is only needed if
98  * you intend to use BuildTupleFromCStrings() to create the return tuple.
99  */
101 
102  /*
103  * memory context used for structures that must live for multiple calls
104  *
105  * multi_call_memory_ctx is set by SRF_FIRSTCALL_INIT() for you, and used
106  * by SRF_RETURN_DONE() for cleanup. It is the most appropriate memory
107  * context for any memory that is to be reused across multiple calls of
108  * the SRF.
109  */
111 
112  /*
113  * OPTIONAL pointer to struct containing tuple description
114  *
115  * tuple_desc is for use when returning tuples (i.e. composite data types)
116  * and is only needed if you are going to build the tuples with
117  * heap_form_tuple() rather than with BuildTupleFromCStrings(). Note that
118  * the TupleDesc pointer stored here should usually have been run through
119  * BlessTupleDesc() first.
120  */
122 
124 
125 /*----------
126  * Support to ease writing functions returning composite types
127  *
128  * External declarations:
129  * get_call_result_type:
130  * Given a function's call info record, determine the kind of datatype
131  * it is supposed to return. If resultTypeId isn't NULL, *resultTypeId
132  * receives the actual datatype OID (this is mainly useful for scalar
133  * result types). If resultTupleDesc isn't NULL, *resultTupleDesc
134  * receives a pointer to a TupleDesc when the result is of a composite
135  * type, or NULL when it's a scalar result or the rowtype could not be
136  * determined. NB: the tupledesc should be copied if it is to be
137  * accessed over a long period.
138  * get_expr_result_type:
139  * Given an expression node, return the same info as for
140  * get_call_result_type. Note: the cases in which rowtypes cannot be
141  * determined are different from the cases for get_call_result_type.
142  * get_func_result_type:
143  * Given only a function's OID, return the same info as for
144  * get_call_result_type. Note: the cases in which rowtypes cannot be
145  * determined are different from the cases for get_call_result_type.
146  * Do *not* use this if you can use one of the others.
147  *
148  * See also get_expr_result_tupdesc(), which is a convenient wrapper around
149  * get_expr_result_type() for use when the caller only cares about
150  * determinable-rowtype cases.
151  *----------
152  */
153 
154 /* Type categories for get_call_result_type and siblings */
155 typedef enum TypeFuncClass
156 {
157  TYPEFUNC_SCALAR, /* scalar result type */
158  TYPEFUNC_COMPOSITE, /* determinable rowtype result */
159  TYPEFUNC_COMPOSITE_DOMAIN, /* domain over determinable rowtype result */
160  TYPEFUNC_RECORD, /* indeterminate rowtype result */
161  TYPEFUNC_OTHER /* bogus type, eg pseudotype */
162 } TypeFuncClass;
163 
165  Oid *resultTypeId,
166  TupleDesc *resultTupleDesc);
168  Oid *resultTypeId,
169  TupleDesc *resultTupleDesc);
170 extern TypeFuncClass get_func_result_type(Oid functionId,
171  Oid *resultTypeId,
172  TupleDesc *resultTupleDesc);
173 
174 extern TupleDesc get_expr_result_tupdesc(Node *expr, bool noError);
175 
176 extern bool resolve_polymorphic_argtypes(int numargs, Oid *argtypes,
177  char *argmodes,
178  Node *call_expr);
179 
180 extern int get_func_arg_info(HeapTuple procTup,
181  Oid **p_argtypes, char ***p_argnames,
182  char **p_argmodes);
183 
184 extern int get_func_input_arg_names(Datum proargnames, Datum proargmodes,
185  char ***arg_names);
186 
187 extern int get_func_trftypes(HeapTuple procTup, Oid **p_trftypes);
188 extern char *get_func_result_name(Oid functionId);
189 
190 extern TupleDesc build_function_result_tupdesc_d(char prokind,
191  Datum proallargtypes,
192  Datum proargmodes,
193  Datum proargnames);
195 
196 
197 /*----------
198  * Support to ease writing functions returning composite types
199  *
200  * External declarations:
201  * TupleDesc BlessTupleDesc(TupleDesc tupdesc) - "Bless" a completed tuple
202  * descriptor so that it can be used to return properly labeled tuples.
203  * You need to call this if you are going to use heap_form_tuple directly.
204  * TupleDescGetAttInMetadata does it for you, however, so no need to call
205  * it if you call TupleDescGetAttInMetadata.
206  * AttInMetadata *TupleDescGetAttInMetadata(TupleDesc tupdesc) - Build an
207  * AttInMetadata struct based on the given TupleDesc. AttInMetadata can
208  * be used in conjunction with C strings to produce a properly formed
209  * tuple.
210  * HeapTuple BuildTupleFromCStrings(AttInMetadata *attinmeta, char **values) -
211  * build a HeapTuple given user data in C string form. values is an array
212  * of C strings, one for each attribute of the return tuple.
213  * Datum HeapTupleHeaderGetDatum(HeapTupleHeader tuple) - convert a
214  * HeapTupleHeader to a Datum.
215  *
216  * Macro declarations:
217  * HeapTupleGetDatum(HeapTuple tuple) - convert a HeapTuple to a Datum.
218  *
219  * Obsolete routines and macros:
220  * TupleDesc RelationNameGetTupleDesc(const char *relname) - Use to get a
221  * TupleDesc based on a named relation.
222  * TupleDesc TypeGetTupleDesc(Oid typeoid, List *colaliases) - Use to get a
223  * TupleDesc based on a type OID.
224  * TupleTableSlot *TupleDescGetSlot(TupleDesc tupdesc) - Builds a
225  * TupleTableSlot, which is not needed anymore.
226  * TupleGetDatum(TupleTableSlot *slot, HeapTuple tuple) - get a Datum
227  * given a tuple and a slot.
228  *----------
229  */
230 
231 #define HeapTupleGetDatum(tuple) HeapTupleHeaderGetDatum((tuple)->t_data)
232 /* obsolete version of above */
233 #define TupleGetDatum(_slot, _tuple) HeapTupleGetDatum(_tuple)
234 
235 extern TupleDesc RelationNameGetTupleDesc(const char *relname);
236 extern TupleDesc TypeGetTupleDesc(Oid typeoid, List *colaliases);
237 
238 /* from execTuples.c */
241 extern HeapTuple BuildTupleFromCStrings(AttInMetadata *attinmeta, char **values);
244 
245 
246 /*----------
247  * Support for Set Returning Functions (SRFs)
248  *
249  * The basic API for SRFs looks something like:
250  *
251  * Datum
252  * my_Set_Returning_Function(PG_FUNCTION_ARGS)
253  * {
254  * FuncCallContext *funcctx;
255  * Datum result;
256  * MemoryContext oldcontext;
257  * <user defined declarations>
258  *
259  * if (SRF_IS_FIRSTCALL())
260  * {
261  * funcctx = SRF_FIRSTCALL_INIT();
262  * // switch context when allocating stuff to be used in later calls
263  * oldcontext = MemoryContextSwitchTo(funcctx->multi_call_memory_ctx);
264  * <user defined code>
265  * <if returning composite>
266  * <build TupleDesc, and perhaps AttInMetaData>
267  * <endif returning composite>
268  * <user defined code>
269  * // return to original context when allocating transient memory
270  * MemoryContextSwitchTo(oldcontext);
271  * }
272  * <user defined code>
273  * funcctx = SRF_PERCALL_SETUP();
274  * <user defined code>
275  *
276  * if (funcctx->call_cntr < funcctx->max_calls)
277  * {
278  * <user defined code>
279  * <obtain result Datum>
280  * SRF_RETURN_NEXT(funcctx, result);
281  * }
282  * else
283  * SRF_RETURN_DONE(funcctx);
284  * }
285  *
286  *----------
287  */
288 
289 /* from funcapi.c */
292 extern void end_MultiFuncCall(PG_FUNCTION_ARGS, FuncCallContext *funcctx);
293 
294 #define SRF_IS_FIRSTCALL() (fcinfo->flinfo->fn_extra == NULL)
295 
296 #define SRF_FIRSTCALL_INIT() init_MultiFuncCall(fcinfo)
297 
298 #define SRF_PERCALL_SETUP() per_MultiFuncCall(fcinfo)
299 
300 #define SRF_RETURN_NEXT(_funcctx, _result) \
301  do { \
302  ReturnSetInfo *rsi; \
303  (_funcctx)->call_cntr++; \
304  rsi = (ReturnSetInfo *) fcinfo->resultinfo; \
305  rsi->isDone = ExprMultipleResult; \
306  PG_RETURN_DATUM(_result); \
307  } while (0)
308 
309 #define SRF_RETURN_NEXT_NULL(_funcctx) \
310  do { \
311  ReturnSetInfo *rsi; \
312  (_funcctx)->call_cntr++; \
313  rsi = (ReturnSetInfo *) fcinfo->resultinfo; \
314  rsi->isDone = ExprMultipleResult; \
315  PG_RETURN_NULL(); \
316  } while (0)
317 
318 #define SRF_RETURN_DONE(_funcctx) \
319  do { \
320  ReturnSetInfo *rsi; \
321  end_MultiFuncCall(fcinfo, _funcctx); \
322  rsi = (ReturnSetInfo *) fcinfo->resultinfo; \
323  rsi->isDone = ExprEndResult; \
324  PG_RETURN_NULL(); \
325  } while (0)
326 
327 /*----------
328  * Support to ease writing of functions dealing with VARIADIC inputs
329  *----------
330  *
331  * This function extracts a set of argument values, types and NULL markers
332  * for a given input function. This returns a set of data:
333  * - **values includes the set of Datum values extracted.
334  * - **types the data type OID for each element.
335  * - **nulls tracks if an element is NULL.
336  *
337  * variadic_start indicates the argument number where the VARIADIC argument
338  * starts.
339  * convert_unknown set to true will enforce the conversion of arguments
340  * with unknown data type to text.
341  *
342  * The return result is the number of elements stored, or -1 in the case of
343  * "VARIADIC NULL".
344  */
345 extern int extract_variadic_args(FunctionCallInfo fcinfo, int variadic_start,
346  bool convert_unknown, Datum **values,
347  Oid **types, bool **nulls);
348 
349 #endif /* FUNCAPI_H */
uint64 call_cntr
Definition: funcapi.h:66
Definition: fmgr.h:56
TupleTableSlot * slot
Definition: funcapi.h:83
Datum HeapTupleHeaderGetDatum(HeapTupleHeader tuple)
Definition: execTuples.c:1284
struct typedefs * types
Definition: ecpg.c:29
int get_func_trftypes(HeapTuple procTup, Oid **p_trftypes)
Definition: funcapi.c:940
TupleDesc build_function_result_tupdesc_t(HeapTuple procTuple)
Definition: funcapi.c:1176
TupleDesc get_expr_result_tupdesc(Node *expr, bool noError)
Definition: funcapi.c:412
TypeFuncClass get_call_result_type(FunctionCallInfo fcinfo, Oid *resultTypeId, TupleDesc *resultTupleDesc)
Definition: funcapi.c:211
Definition: nodes.h:517
TupleDesc build_function_result_tupdesc_d(char prokind, Datum proallargtypes, Datum proargmodes, Datum proargnames)
Definition: funcapi.c:1226
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:846
unsigned int Oid
Definition: postgres_ext.h:31
Oid * attioparams
Definition: funcapi.h:45
TupleDesc tuple_desc
Definition: funcapi.h:121
signed int int32
Definition: c.h:313
int get_func_input_arg_names(Datum proargnames, Datum proargmodes, char ***arg_names)
Definition: funcapi.c:988
TupleDesc TypeGetTupleDesc(Oid typeoid, List *colaliases)
Definition: funcapi.c:1377
TupleDesc RelationNameGetTupleDesc(const char *relname)
Definition: funcapi.c:1344
AttInMetadata * attinmeta
Definition: funcapi.h:100
TupleDesc tupdesc
Definition: funcapi.h:39
struct FuncCallContext FuncCallContext
TypeFuncClass
Definition: funcapi.h:155
void end_MultiFuncCall(PG_FUNCTION_ARGS, FuncCallContext *funcctx)
Definition: funcapi.c:155
FuncCallContext * init_MultiFuncCall(PG_FUNCTION_ARGS)
Definition: funcapi.c:52
struct AttInMetadata AttInMetadata
uintptr_t Datum
Definition: postgres.h:367
TypeFuncClass get_expr_result_type(Node *expr, Oid *resultTypeId, TupleDesc *resultTupleDesc)
Definition: funcapi.c:227
TypeFuncClass get_func_result_type(Oid functionId, Oid *resultTypeId, TupleDesc *resultTupleDesc)
Definition: funcapi.c:272
TupleDesc BlessTupleDesc(TupleDesc tupdesc)
Definition: execTuples.c:1109
MemoryContext multi_call_memory_ctx
Definition: funcapi.h:110
char * get_func_result_name(Oid functionId)
Definition: funcapi.c:1073
FuncCallContext * per_MultiFuncCall(PG_FUNCTION_ARGS)
Definition: funcapi.c:128
AttInMetadata * TupleDescGetAttInMetadata(TupleDesc tupdesc)
Definition: execTuples.c:1146
static Datum values[MAXATTR]
Definition: bootstrap.c:164
void * user_fctx
Definition: funcapi.h:91
bool resolve_polymorphic_argtypes(int numargs, Oid *argtypes, char *argmodes, Node *call_expr)
Definition: funcapi.c:644
#define PG_FUNCTION_ARGS
Definition: fmgr.h:163
HeapTuple BuildTupleFromCStrings(AttInMetadata *attinmeta, char **values)
Definition: execTuples.c:1195
FmgrInfo * attinfuncs
Definition: funcapi.h:42
TupleTableSlot * TupleDescGetSlot(TupleDesc tupdesc)
Definition: execTuples.c:1126
int extract_variadic_args(FunctionCallInfo fcinfo, int variadic_start, bool convert_unknown, Datum **values, Oid **types, bool **nulls)
Definition: funcapi.c:1479
Definition: pg_list.h:45
uint64 max_calls
Definition: funcapi.h:75