PostgreSQL Source Code  git master
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros
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  *
6  * This file must be included by all Postgres modules that either define
7  * or call FUNCAPI-callable functions or macros.
8  *
9  *
10  * Copyright (c) 2002-2017, PostgreSQL Global Development Group
11  *
12  * src/include/funcapi.h
13  *
14  *-------------------------------------------------------------------------
15  */
16 #ifndef FUNCAPI_H
17 #define FUNCAPI_H
18 
19 #include "fmgr.h"
20 #include "access/tupdesc.h"
21 #include "executor/executor.h"
22 #include "executor/tuptable.h"
23 
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 */
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  */
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 result slot
78  *
79  * This is obsolete and only present for backwards compatibility, viz,
80  * user-defined SRFs that use the deprecated TupleDescGetSlot().
81  */
83 
84  /*
85  * OPTIONAL pointer to miscellaneous user-provided context information
86  *
87  * user_fctx is for use as a pointer to your own struct to retain
88  * arbitrary context information between calls of your function.
89  */
90  void *user_fctx;
91 
92  /*
93  * OPTIONAL pointer to struct containing attribute type input metadata
94  *
95  * attinmeta is for use when returning tuples (i.e. composite data types)
96  * and is not used when returning base data types. It is only needed if
97  * you intend to use BuildTupleFromCStrings() to create the return tuple.
98  */
100 
101  /*
102  * memory context used for structures that must live for multiple calls
103  *
104  * multi_call_memory_ctx is set by SRF_FIRSTCALL_INIT() for you, and used
105  * by SRF_RETURN_DONE() for cleanup. It is the most appropriate memory
106  * context for any memory that is to be reused across multiple calls of
107  * the SRF.
108  */
110 
111  /*
112  * OPTIONAL pointer to struct containing tuple description
113  *
114  * tuple_desc is for use when returning tuples (i.e. composite data types)
115  * and is only needed if you are going to build the tuples with
116  * heap_form_tuple() rather than with BuildTupleFromCStrings(). Note that
117  * the TupleDesc pointer stored here should usually have been run through
118  * BlessTupleDesc() first.
119  */
121 
123 
124 /*----------
125  * Support to ease writing functions returning composite types
126  *
127  * External declarations:
128  * get_call_result_type:
129  * Given a function's call info record, determine the kind of datatype
130  * it is supposed to return. If resultTypeId isn't NULL, *resultTypeId
131  * receives the actual datatype OID (this is mainly useful for scalar
132  * result types). If resultTupleDesc isn't NULL, *resultTupleDesc
133  * receives a pointer to a TupleDesc when the result is of a composite
134  * type, or NULL when it's a scalar result or the rowtype could not be
135  * determined. NB: the tupledesc should be copied if it is to be
136  * accessed over a long period.
137  * get_expr_result_type:
138  * Given an expression node, return the same info as for
139  * get_call_result_type. Note: the cases in which rowtypes cannot be
140  * determined are different from the cases for get_call_result_type.
141  * get_func_result_type:
142  * Given only a function's OID, return the same info as for
143  * get_call_result_type. Note: the cases in which rowtypes cannot be
144  * determined are different from the cases for get_call_result_type.
145  * Do *not* use this if you can use one of the others.
146  *----------
147  */
148 
149 /* Type categories for get_call_result_type and siblings */
150 typedef enum TypeFuncClass
151 {
152  TYPEFUNC_SCALAR, /* scalar result type */
153  TYPEFUNC_COMPOSITE, /* determinable rowtype result */
154  TYPEFUNC_RECORD, /* indeterminate rowtype result */
155  TYPEFUNC_OTHER /* bogus type, eg pseudotype */
156 } TypeFuncClass;
157 
159  Oid *resultTypeId,
160  TupleDesc *resultTupleDesc);
162  Oid *resultTypeId,
163  TupleDesc *resultTupleDesc);
164 extern TypeFuncClass get_func_result_type(Oid functionId,
165  Oid *resultTypeId,
166  TupleDesc *resultTupleDesc);
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(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  * Macro 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  * TupleTableSlot *TupleDescGetSlot(TupleDesc tupdesc) - Builds a
216  * TupleTableSlot, which is not needed anymore.
217  * TupleGetDatum(TupleTableSlot *slot, HeapTuple tuple) - get a Datum
218  * given a tuple and a slot.
219  *----------
220  */
221 
222 #define HeapTupleGetDatum(tuple) HeapTupleHeaderGetDatum((tuple)->t_data)
223 /* obsolete version of above */
224 #define TupleGetDatum(_slot, _tuple) HeapTupleGetDatum(_tuple)
225 
226 extern TupleDesc RelationNameGetTupleDesc(const char *relname);
227 extern TupleDesc TypeGetTupleDesc(Oid typeoid, List *colaliases);
228 
229 /* from execTuples.c */
230 extern TupleDesc BlessTupleDesc(TupleDesc tupdesc);
232 extern HeapTuple BuildTupleFromCStrings(AttInMetadata *attinmeta, char **values);
234 extern TupleTableSlot *TupleDescGetSlot(TupleDesc tupdesc);
235 
236 
237 /*----------
238  * Support for Set Returning Functions (SRFs)
239  *
240  * The basic API for SRFs looks something like:
241  *
242  * Datum
243  * my_Set_Returning_Function(PG_FUNCTION_ARGS)
244  * {
245  * FuncCallContext *funcctx;
246  * Datum result;
247  * MemoryContext oldcontext;
248  * <user defined declarations>
249  *
250  * if (SRF_IS_FIRSTCALL())
251  * {
252  * funcctx = SRF_FIRSTCALL_INIT();
253  * // switch context when allocating stuff to be used in later calls
254  * oldcontext = MemoryContextSwitchTo(funcctx->multi_call_memory_ctx);
255  * <user defined code>
256  * <if returning composite>
257  * <build TupleDesc, and perhaps AttInMetaData>
258  * <endif returning composite>
259  * <user defined code>
260  * // return to original context when allocating transient memory
261  * MemoryContextSwitchTo(oldcontext);
262  * }
263  * <user defined code>
264  * funcctx = SRF_PERCALL_SETUP();
265  * <user defined code>
266  *
267  * if (funcctx->call_cntr < funcctx->max_calls)
268  * {
269  * <user defined code>
270  * <obtain result Datum>
271  * SRF_RETURN_NEXT(funcctx, result);
272  * }
273  * else
274  * SRF_RETURN_DONE(funcctx);
275  * }
276  *
277  *----------
278  */
279 
280 /* from funcapi.c */
283 extern void end_MultiFuncCall(PG_FUNCTION_ARGS, FuncCallContext *funcctx);
284 
285 #define SRF_IS_FIRSTCALL() (fcinfo->flinfo->fn_extra == NULL)
286 
287 #define SRF_FIRSTCALL_INIT() init_MultiFuncCall(fcinfo)
288 
289 #define SRF_PERCALL_SETUP() per_MultiFuncCall(fcinfo)
290 
291 #define SRF_RETURN_NEXT(_funcctx, _result) \
292  do { \
293  ReturnSetInfo *rsi; \
294  (_funcctx)->call_cntr++; \
295  rsi = (ReturnSetInfo *) fcinfo->resultinfo; \
296  rsi->isDone = ExprMultipleResult; \
297  PG_RETURN_DATUM(_result); \
298  } while (0)
299 
300 #define SRF_RETURN_NEXT_NULL(_funcctx) \
301  do { \
302  ReturnSetInfo *rsi; \
303  (_funcctx)->call_cntr++; \
304  rsi = (ReturnSetInfo *) fcinfo->resultinfo; \
305  rsi->isDone = ExprMultipleResult; \
306  PG_RETURN_NULL(); \
307  } while (0)
308 
309 #define SRF_RETURN_DONE(_funcctx) \
310  do { \
311  ReturnSetInfo *rsi; \
312  end_MultiFuncCall(fcinfo, _funcctx); \
313  rsi = (ReturnSetInfo *) fcinfo->resultinfo; \
314  rsi->isDone = ExprEndResult; \
315  PG_RETURN_NULL(); \
316  } while (0)
317 
318 #endif /* FUNCAPI_H */
uint64 call_cntr
Definition: funcapi.h:65
Definition: fmgr.h:56
TupleTableSlot * slot
Definition: funcapi.h:82
Datum HeapTupleHeaderGetDatum(HeapTupleHeader tuple)
Definition: execTuples.c:1201
int get_func_trftypes(HeapTuple procTup, Oid **p_trftypes)
Definition: funcapi.c:885
TupleDesc build_function_result_tupdesc_t(HeapTuple procTuple)
Definition: funcapi.c:1121
TypeFuncClass get_call_result_type(FunctionCallInfo fcinfo, Oid *resultTypeId, TupleDesc *resultTupleDesc)
Definition: funcapi.c:211
Definition: nodes.h:509
int32 * atttypmods
Definition: funcapi.h:47
int get_func_arg_info(HeapTuple procTup, Oid **p_argtypes, char ***p_argnames, char **p_argmodes)
Definition: funcapi.c:791
unsigned int Oid
Definition: postgres_ext.h:31
Oid * attioparams
Definition: funcapi.h:44
TupleDesc tuple_desc
Definition: funcapi.h:120
signed int int32
Definition: c.h:256
int get_func_input_arg_names(Datum proargnames, Datum proargmodes, char ***arg_names)
Definition: funcapi.c:933
TupleDesc TypeGetTupleDesc(Oid typeoid, List *colaliases)
Definition: funcapi.c:1319
TupleDesc build_function_result_tupdesc_d(Datum proallargtypes, Datum proargmodes, Datum proargnames)
Definition: funcapi.c:1169
TupleDesc RelationNameGetTupleDesc(const char *relname)
Definition: funcapi.c:1286
AttInMetadata * attinmeta
Definition: funcapi.h:99
TupleDesc tupdesc
Definition: funcapi.h:38
struct FuncCallContext FuncCallContext
TypeFuncClass
Definition: funcapi.h:150
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:269
TupleDesc BlessTupleDesc(TupleDesc tupdesc)
Definition: execTuples.c:1031
MemoryContext multi_call_memory_ctx
Definition: funcapi.h:109
char * get_func_result_name(Oid functionId)
Definition: funcapi.c:1018
FuncCallContext * per_MultiFuncCall(PG_FUNCTION_ARGS)
Definition: funcapi.c:128
AttInMetadata * TupleDescGetAttInMetadata(TupleDesc tupdesc)
Definition: execTuples.c:1068
static Datum values[MAXATTR]
Definition: bootstrap.c:163
void * user_fctx
Definition: funcapi.h:90
bool resolve_polymorphic_argtypes(int numargs, Oid *argtypes, char *argmodes, Node *call_expr)
Definition: funcapi.c:597
#define PG_FUNCTION_ARGS
Definition: fmgr.h:158
HeapTuple BuildTupleFromCStrings(AttInMetadata *attinmeta, char **values)
Definition: execTuples.c:1115
FmgrInfo * attinfuncs
Definition: funcapi.h:41
TupleTableSlot * TupleDescGetSlot(TupleDesc tupdesc)
Definition: execTuples.c:1048
Definition: pg_list.h:45
uint64 max_calls
Definition: funcapi.h:74