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 */ 39 TupleDesc tupdesc; 40 41 /* array of attribute type input function finfo */ 42 FmgrInfo *attinfuncs; 43 44 /* array of attribute type i/o parameter OIDs */ 45 Oid *attioparams; 46 47 /* array of attribute typmod */ 48 int32 *atttypmods; 49 } AttInMetadata; 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 */ 83 TupleTableSlot *slot; 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 */ 100 AttInMetadata *attinmeta; 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 */ 110 MemoryContext multi_call_memory_ctx; 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 */ 121 TupleDesc tuple_desc; 122 123 } FuncCallContext; 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 */ 149 150 /* Type categories for get_call_result_type and siblings */ 151 typedef enum TypeFuncClass 152 { 153 TYPEFUNC_SCALAR, /* scalar result type */ 154 TYPEFUNC_COMPOSITE, /* determinable rowtype result */ 155 TYPEFUNC_RECORD, /* indeterminate rowtype result */ 156 TYPEFUNC_OTHER /* bogus type, eg pseudotype */ 157 } TypeFuncClass; 158 159 extern TypeFuncClass get_call_result_type(FunctionCallInfo fcinfo, 160 Oid *resultTypeId, 161 TupleDesc *resultTupleDesc); 162 extern TypeFuncClass get_expr_result_type(Node *expr, 163 Oid *resultTypeId, 164 TupleDesc *resultTupleDesc); 165 extern TypeFuncClass get_func_result_type(Oid functionId, 166 Oid *resultTypeId, 167 TupleDesc *resultTupleDesc); 168 169 extern bool resolve_polymorphic_argtypes(int numargs, Oid *argtypes, 170 char *argmodes, 171 Node *call_expr); 172 173 extern int get_func_arg_info(HeapTuple procTup, 174 Oid **p_argtypes, char ***p_argnames, 175 char **p_argmodes); 176 177 extern int get_func_input_arg_names(Datum proargnames, Datum proargmodes, 178 char ***arg_names); 179 180 extern int get_func_trftypes(HeapTuple procTup, Oid **p_trftypes); 181 extern char *get_func_result_name(Oid functionId); 182 183 extern TupleDesc build_function_result_tupdesc_d(Datum proallargtypes, 184 Datum proargmodes, 185 Datum proargnames); 186 extern TupleDesc build_function_result_tupdesc_t(HeapTuple procTuple); 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 * TupleTableSlot *TupleDescGetSlot(TupleDesc tupdesc) - Builds a 217 * TupleTableSlot, which is not needed anymore. 218 * TupleGetDatum(TupleTableSlot *slot, HeapTuple tuple) - get a Datum 219 * given a tuple and a slot. 220 *---------- 221 */ 222 223 #define HeapTupleGetDatum(tuple) HeapTupleHeaderGetDatum((tuple)->t_data) 224 /* obsolete version of above */ 225 #define TupleGetDatum(_slot, _tuple) HeapTupleGetDatum(_tuple) 226 227 extern TupleDesc RelationNameGetTupleDesc(const char *relname); 228 extern TupleDesc TypeGetTupleDesc(Oid typeoid, List *colaliases); 229 230 /* from execTuples.c */ 231 extern TupleDesc BlessTupleDesc(TupleDesc tupdesc); 232 extern AttInMetadata *TupleDescGetAttInMetadata(TupleDesc tupdesc); 233 extern HeapTuple BuildTupleFromCStrings(AttInMetadata *attinmeta, char **values); 234 extern Datum HeapTupleHeaderGetDatum(HeapTupleHeader tuple); 235 extern TupleTableSlot *TupleDescGetSlot(TupleDesc tupdesc); 236 237 238 /*---------- 239 * Support for Set Returning Functions (SRFs) 240 * 241 * The basic API for SRFs using ValuePerCall mode looks something like this: 242 * 243 * Datum 244 * my_Set_Returning_Function(PG_FUNCTION_ARGS) 245 * { 246 * FuncCallContext *funcctx; 247 * Datum result; 248 * MemoryContext oldcontext; 249 * <user defined declarations> 250 * 251 * if (SRF_IS_FIRSTCALL()) 252 * { 253 * funcctx = SRF_FIRSTCALL_INIT(); 254 * // switch context when allocating stuff to be used in later calls 255 * oldcontext = MemoryContextSwitchTo(funcctx->multi_call_memory_ctx); 256 * <user defined code> 257 * <if returning composite> 258 * <build TupleDesc, and perhaps AttInMetaData> 259 * <endif returning composite> 260 * <user defined code> 261 * // return to original context when allocating transient memory 262 * MemoryContextSwitchTo(oldcontext); 263 * } 264 * <user defined code> 265 * funcctx = SRF_PERCALL_SETUP(); 266 * <user defined code> 267 * 268 * if (funcctx->call_cntr < funcctx->max_calls) 269 * { 270 * <user defined code> 271 * <obtain result Datum> 272 * SRF_RETURN_NEXT(funcctx, result); 273 * } 274 * else 275 * SRF_RETURN_DONE(funcctx); 276 * } 277 * 278 * NOTE: there is no guarantee that a SRF using ValuePerCall mode will be 279 * run to completion; for example, a query with LIMIT might stop short of 280 * fetching all the rows. Therefore, do not expect that you can do resource 281 * cleanup just before SRF_RETURN_DONE(). You need not worry about releasing 282 * memory allocated in multi_call_memory_ctx, but holding file descriptors or 283 * other non-memory resources open across calls is a bug. SRFs that need 284 * such resources should not use these macros, but instead populate a 285 * tuplestore during a single call, and return that using SFRM_Materialize 286 * mode (see fmgr/README). Alternatively, set up a callback to release 287 * resources at query shutdown, using RegisterExprContextCallback(). 288 * 289 *---------- 290 */ 291 292 /* from funcapi.c */ 293 extern FuncCallContext *init_MultiFuncCall(PG_FUNCTION_ARGS); 294 extern FuncCallContext *per_MultiFuncCall(PG_FUNCTION_ARGS); 295 extern void end_MultiFuncCall(PG_FUNCTION_ARGS, FuncCallContext *funcctx); 296 297 #define SRF_IS_FIRSTCALL() (fcinfo->flinfo->fn_extra == NULL) 298 299 #define SRF_FIRSTCALL_INIT() init_MultiFuncCall(fcinfo) 300 301 #define SRF_PERCALL_SETUP() per_MultiFuncCall(fcinfo) 302 303 #define SRF_RETURN_NEXT(_funcctx, _result) \ 304 do { \ 305 ReturnSetInfo *rsi; \ 306 (_funcctx)->call_cntr++; \ 307 rsi = (ReturnSetInfo *) fcinfo->resultinfo; \ 308 rsi->isDone = ExprMultipleResult; \ 309 PG_RETURN_DATUM(_result); \ 310 } while (0) 311 312 #define SRF_RETURN_NEXT_NULL(_funcctx) \ 313 do { \ 314 ReturnSetInfo *rsi; \ 315 (_funcctx)->call_cntr++; \ 316 rsi = (ReturnSetInfo *) fcinfo->resultinfo; \ 317 rsi->isDone = ExprMultipleResult; \ 318 PG_RETURN_NULL(); \ 319 } while (0) 320 321 #define SRF_RETURN_DONE(_funcctx) \ 322 do { \ 323 ReturnSetInfo *rsi; \ 324 end_MultiFuncCall(fcinfo, _funcctx); \ 325 rsi = (ReturnSetInfo *) fcinfo->resultinfo; \ 326 rsi->isDone = ExprEndResult; \ 327 PG_RETURN_NULL(); \ 328 } while (0) 329 330 /*---------- 331 * Support to ease writing of functions dealing with VARIADIC inputs 332 *---------- 333 * 334 * This function extracts a set of argument values, types and NULL markers 335 * for a given input function. This returns a set of data: 336 * - **values includes the set of Datum values extracted. 337 * - **types the data type OID for each element. 338 * - **nulls tracks if an element is NULL. 339 * 340 * variadic_start indicates the argument number where the VARIADIC argument 341 * starts. 342 * convert_unknown set to true will enforce the conversion of arguments 343 * with unknown data type to text. 344 * 345 * The return result is the number of elements stored, or -1 in the case of 346 * "VARIADIC NULL". 347 */ 348 extern int extract_variadic_args(FunctionCallInfo fcinfo, int variadic_start, 349 bool convert_unknown, Datum **values, 350 Oid **types, bool **nulls); 351 352 #endif /* FUNCAPI_H */ 353