1 /*-------------------------------------------------------------------------
4 * Definitions for functions which return composite type and/or sets
6 * This file must be included by all Postgres modules that either define
7 * or call FUNCAPI-callable functions or macros.
10 * Copyright (c) 2002-2005, PostgreSQL Global Development Group
12 * $PostgreSQL: pgsql/src/include/funcapi.h,v 1.21 2005/11/22 18:17:29 momjian Exp $
14 *-------------------------------------------------------------------------
20 #include "access/tupdesc.h"
21 #include "executor/executor.h"
22 #include "executor/tuptable.h"
25 /*-------------------------------------------------------------------------
26 * Support to ease writing Functions returning composite types
27 *-------------------------------------------------------------------------
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.
35 typedef struct AttInMetadata
40 /* array of attribute type input function finfo */
43 /* array of attribute type i/o parameter OIDs */
46 /* array of attribute typmod */
50 /*-------------------------------------------------------------------------
51 * Support struct to ease writing Set Returning Functions (SRFs)
52 *-------------------------------------------------------------------------
54 * This struct holds function context for Set Returning Functions.
55 * Use fn_extra to hold a pointer to it across calls
57 typedef struct FuncCallContext
60 * Number of times we've been called before
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.
68 * OPTIONAL maximum number of calls
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
77 * OPTIONAL pointer to result slot
79 * This is obsolete and only present for backwards compatibility, viz,
80 * user-defined SRFs that use the deprecated TupleDescGetSlot().
85 * OPTIONAL pointer to miscellaneous user-provided context information
87 * user_fctx is for use as a pointer to your own struct to retain
88 * arbitrary context information between calls of your function.
93 * OPTIONAL pointer to struct containing attribute type input metadata
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.
99 AttInMetadata *attinmeta;
102 * memory context used for structures that must live for multiple calls
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
109 MemoryContext multi_call_memory_ctx;
112 * OPTIONAL pointer to struct containing tuple description
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_formtuple() rather than with BuildTupleFromCStrings(). Note that
117 * the TupleDesc pointer stored here should usually have been run through
118 * BlessTupleDesc() first.
120 TupleDesc tuple_desc;
125 * Support to ease writing functions returning composite types
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.
149 /* Type categories for get_call_result_type and siblings */
150 typedef enum TypeFuncClass
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 */
158 extern TypeFuncClass get_call_result_type(FunctionCallInfo fcinfo,
160 TupleDesc *resultTupleDesc);
161 extern TypeFuncClass get_expr_result_type(Node *expr,
163 TupleDesc *resultTupleDesc);
164 extern TypeFuncClass get_func_result_type(Oid functionId,
166 TupleDesc *resultTupleDesc);
168 extern char *get_func_result_name(Oid functionId);
170 extern bool resolve_polymorphic_argtypes(int numargs, Oid *argtypes,
174 extern TupleDesc build_function_result_tupdesc_d(Datum proallargtypes,
177 extern TupleDesc build_function_result_tupdesc_t(HeapTuple procTuple);
181 * Support to ease writing functions returning composite types
183 * External declarations:
184 * TupleDesc BlessTupleDesc(TupleDesc tupdesc) - "Bless" a completed tuple
185 * descriptor so that it can be used to return properly labeled tuples.
186 * You need to call this if you are going to use heap_formtuple directly.
187 * TupleDescGetAttInMetadata does it for you, however, so no need to call
188 * it if you call TupleDescGetAttInMetadata.
189 * AttInMetadata *TupleDescGetAttInMetadata(TupleDesc tupdesc) - Build an
190 * AttInMetadata struct based on the given TupleDesc. AttInMetadata can
191 * be used in conjunction with C strings to produce a properly formed
193 * HeapTuple BuildTupleFromCStrings(AttInMetadata *attinmeta, char **values) -
194 * build a HeapTuple given user data in C string form. values is an array
195 * of C strings, one for each attribute of the return tuple.
197 * Macro declarations:
198 * HeapTupleGetDatum(HeapTuple tuple) - convert a HeapTuple to a Datum.
200 * Obsolete routines and macros:
201 * TupleDesc RelationNameGetTupleDesc(const char *relname) - Use to get a
202 * TupleDesc based on a named relation.
203 * TupleDesc TypeGetTupleDesc(Oid typeoid, List *colaliases) - Use to get a
204 * TupleDesc based on a type OID.
205 * TupleTableSlot *TupleDescGetSlot(TupleDesc tupdesc) - Builds a
206 * TupleTableSlot, which is not needed anymore.
207 * TupleGetDatum(TupleTableSlot *slot, HeapTuple tuple) - get a Datum
208 * given a tuple and a slot.
212 #define HeapTupleGetDatum(_tuple) PointerGetDatum((_tuple)->t_data)
213 /* obsolete version of above */
214 #define TupleGetDatum(_slot, _tuple) PointerGetDatum((_tuple)->t_data)
216 extern TupleDesc RelationNameGetTupleDesc(const char *relname);
217 extern TupleDesc TypeGetTupleDesc(Oid typeoid, List *colaliases);
219 /* from execTuples.c */
220 extern TupleDesc BlessTupleDesc(TupleDesc tupdesc);
221 extern AttInMetadata *TupleDescGetAttInMetadata(TupleDesc tupdesc);
222 extern HeapTuple BuildTupleFromCStrings(AttInMetadata *attinmeta, char **values);
223 extern TupleTableSlot *TupleDescGetSlot(TupleDesc tupdesc);
227 * Support for Set Returning Functions (SRFs)
229 * The basic API for SRFs looks something like:
232 * my_Set_Returning_Function(PG_FUNCTION_ARGS)
234 * FuncCallContext *funcctx;
236 * MemoryContext oldcontext;
237 * <user defined declarations>
239 * if (SRF_IS_FIRSTCALL())
241 * funcctx = SRF_FIRSTCALL_INIT();
242 * // switch context when allocating stuff to be used in later calls
243 * oldcontext = MemoryContextSwitchTo(funcctx->multi_call_memory_ctx);
244 * <user defined code>
245 * <if returning composite>
246 * <build TupleDesc, and perhaps AttInMetaData>
247 * <endif returning composite>
248 * <user defined code>
249 * // return to original context when allocating transient memory
250 * MemoryContextSwitchTo(oldcontext);
252 * <user defined code>
253 * funcctx = SRF_PERCALL_SETUP();
254 * <user defined code>
256 * if (funcctx->call_cntr < funcctx->max_calls)
258 * <user defined code>
259 * <obtain result Datum>
260 * SRF_RETURN_NEXT(funcctx, result);
263 * SRF_RETURN_DONE(funcctx);
270 extern FuncCallContext *init_MultiFuncCall(PG_FUNCTION_ARGS);
271 extern FuncCallContext *per_MultiFuncCall(PG_FUNCTION_ARGS);
272 extern void end_MultiFuncCall(PG_FUNCTION_ARGS, FuncCallContext *funcctx);
274 #define SRF_IS_FIRSTCALL() (fcinfo->flinfo->fn_extra == NULL)
276 #define SRF_FIRSTCALL_INIT() init_MultiFuncCall(fcinfo)
278 #define SRF_PERCALL_SETUP() per_MultiFuncCall(fcinfo)
280 #define SRF_RETURN_NEXT(_funcctx, _result) \
282 ReturnSetInfo *rsi; \
283 (_funcctx)->call_cntr++; \
284 rsi = (ReturnSetInfo *) fcinfo->resultinfo; \
285 rsi->isDone = ExprMultipleResult; \
286 PG_RETURN_DATUM(_result); \
289 #define SRF_RETURN_DONE(_funcctx) \
291 ReturnSetInfo *rsi; \
292 end_MultiFuncCall(fcinfo, _funcctx); \
293 rsi = (ReturnSetInfo *) fcinfo->resultinfo; \
294 rsi->isDone = ExprEndResult; \
298 #endif /* FUNCAPI_H */