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-2017, 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(Datum proallargtypes,
191  Datum proargmodes,
192  Datum proargnames);
194 
195 
196 /*----------
197  * Support to ease writing functions returning composite types
198  *
199  * External declarations:
200  * TupleDesc BlessTupleDesc(TupleDesc tupdesc) - "Bless" a completed tuple
201  * descriptor so that it can be used to return properly labeled tuples.
202  * You need to call this if you are going to use heap_form_tuple directly.
203  * TupleDescGetAttInMetadata does it for you, however, so no need to call
204  * it if you call TupleDescGetAttInMetadata.
205  * AttInMetadata *TupleDescGetAttInMetadata(TupleDesc tupdesc) - Build an
206  * AttInMetadata struct based on the given TupleDesc. AttInMetadata can
207  * be used in conjunction with C strings to produce a properly formed
208  * tuple.
209  * HeapTuple BuildTupleFromCStrings(AttInMetadata *attinmeta, char **values) -
210  * build a HeapTuple given user data in C string form. values is an array
211  * of C strings, one for each attribute of the return tuple.
212  * Datum HeapTupleHeaderGetDatum(HeapTupleHeader tuple) - convert a
213  * HeapTupleHeader to a Datum.
214  *
215  * Macro declarations:
216  * HeapTupleGetDatum(HeapTuple tuple) - convert a HeapTuple to a Datum.
217  *
218  * Obsolete routines and macros:
219  * TupleDesc RelationNameGetTupleDesc(const char *relname) - Use to get a
220  * TupleDesc based on a named relation.
221  * TupleDesc TypeGetTupleDesc(Oid typeoid, List *colaliases) - Use to get a
222  * TupleDesc based on a type OID.
223  * TupleTableSlot *TupleDescGetSlot(TupleDesc tupdesc) - Builds a
224  * TupleTableSlot, which is not needed anymore.
225  * TupleGetDatum(TupleTableSlot *slot, HeapTuple tuple) - get a Datum
226  * given a tuple and a slot.
227  *----------
228  */
229 
230 #define HeapTupleGetDatum(tuple) HeapTupleHeaderGetDatum((tuple)->t_data)
231 /* obsolete version of above */
232 #define TupleGetDatum(_slot, _tuple) HeapTupleGetDatum(_tuple)
233 
234 extern TupleDesc RelationNameGetTupleDesc(const char *relname);
235 extern TupleDesc TypeGetTupleDesc(Oid typeoid, List *colaliases);
236 
237 /* from execTuples.c */
240 extern HeapTuple BuildTupleFromCStrings(AttInMetadata *attinmeta, char **values);
243 
244 
245 /*----------
246  * Support for Set Returning Functions (SRFs)
247  *
248  * The basic API for SRFs looks something like:
249  *
250  * Datum
251  * my_Set_Returning_Function(PG_FUNCTION_ARGS)
252  * {
253  * FuncCallContext *funcctx;
254  * Datum result;
255  * MemoryContext oldcontext;
256  * <user defined declarations>
257  *
258  * if (SRF_IS_FIRSTCALL())
259  * {
260  * funcctx = SRF_FIRSTCALL_INIT();
261  * // switch context when allocating stuff to be used in later calls
262  * oldcontext = MemoryContextSwitchTo(funcctx->multi_call_memory_ctx);
263  * <user defined code>
264  * <if returning composite>
265  * <build TupleDesc, and perhaps AttInMetaData>
266  * <endif returning composite>
267  * <user defined code>
268  * // return to original context when allocating transient memory
269  * MemoryContextSwitchTo(oldcontext);
270  * }
271  * <user defined code>
272  * funcctx = SRF_PERCALL_SETUP();
273  * <user defined code>
274  *
275  * if (funcctx->call_cntr < funcctx->max_calls)
276  * {
277  * <user defined code>
278  * <obtain result Datum>
279  * SRF_RETURN_NEXT(funcctx, result);
280  * }
281  * else
282  * SRF_RETURN_DONE(funcctx);
283  * }
284  *
285  *----------
286  */
287 
288 /* from funcapi.c */
291 extern void end_MultiFuncCall(PG_FUNCTION_ARGS, FuncCallContext *funcctx);
292 
293 #define SRF_IS_FIRSTCALL() (fcinfo->flinfo->fn_extra == NULL)
294 
295 #define SRF_FIRSTCALL_INIT() init_MultiFuncCall(fcinfo)
296 
297 #define SRF_PERCALL_SETUP() per_MultiFuncCall(fcinfo)
298 
299 #define SRF_RETURN_NEXT(_funcctx, _result) \
300  do { \
301  ReturnSetInfo *rsi; \
302  (_funcctx)->call_cntr++; \
303  rsi = (ReturnSetInfo *) fcinfo->resultinfo; \
304  rsi->isDone = ExprMultipleResult; \
305  PG_RETURN_DATUM(_result); \
306  } while (0)
307 
308 #define SRF_RETURN_NEXT_NULL(_funcctx) \
309  do { \
310  ReturnSetInfo *rsi; \
311  (_funcctx)->call_cntr++; \
312  rsi = (ReturnSetInfo *) fcinfo->resultinfo; \
313  rsi->isDone = ExprMultipleResult; \
314  PG_RETURN_NULL(); \
315  } while (0)
316 
317 #define SRF_RETURN_DONE(_funcctx) \
318  do { \
319  ReturnSetInfo *rsi; \
320  end_MultiFuncCall(fcinfo, _funcctx); \
321  rsi = (ReturnSetInfo *) fcinfo->resultinfo; \
322  rsi->isDone = ExprEndResult; \
323  PG_RETURN_NULL(); \
324  } while (0)
325 
326 /*----------
327  * Support to ease writing of functions dealing with VARIADIC inputs
328  *----------
329  *
330  * This function extracts a set of argument values, types and NULL markers
331  * for a given input function. This returns a set of data:
332  * - **values includes the set of Datum values extracted.
333  * - **types the data type OID for each element.
334  * - **nulls tracks if an element is NULL.
335  *
336  * variadic_start indicates the argument number where the VARIADIC argument
337  * starts.
338  * convert_unknown set to true will enforce the conversion of arguments
339  * with unknown data type to text.
340  *
341  * The return result is the number of elements stored, or -1 in the case of
342  * "VARIADIC NULL".
343  */
344 extern int extract_variadic_args(FunctionCallInfo fcinfo, int variadic_start,
345  bool convert_unknown, Datum **values,
346  Oid **types, bool **nulls);
347 
348 #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:1204
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:512
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:294
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:1374
TupleDesc build_function_result_tupdesc_d(Datum proallargtypes, Datum proargmodes, Datum proargnames)
Definition: funcapi.c:1224
TupleDesc RelationNameGetTupleDesc(const char *relname)
Definition: funcapi.c:1341
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:372
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:1032
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:1069
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:158
HeapTuple BuildTupleFromCStrings(AttInMetadata *attinmeta, char **values)
Definition: execTuples.c:1118
FmgrInfo * attinfuncs
Definition: funcapi.h:42
TupleTableSlot * TupleDescGetSlot(TupleDesc tupdesc)
Definition: execTuples.c:1049
int extract_variadic_args(FunctionCallInfo fcinfo, int variadic_start, bool convert_unknown, Datum **values, Oid **types, bool **nulls)
Definition: funcapi.c:1476
Definition: pg_list.h:45
uint64 max_calls
Definition: funcapi.h:75