/*------------------------------------------------------------------------- * * funcapi.h * Definitions for functions which return composite type and/or sets * or work on VARIADIC inputs. * * This file must be included by all Postgres modules that either define * or call FUNCAPI-callable functions or macros. * * * Copyright (c) 2002-2024, PostgreSQL Global Development Group * * src/include/funcapi.h * *------------------------------------------------------------------------- */ #ifndef FUNCAPI_H #define FUNCAPI_H #include "access/tupdesc.h" #include "executor/executor.h" #include "executor/tuptable.h" #include "fmgr.h" /*------------------------------------------------------------------------- * Support to ease writing Functions returning composite types *------------------------------------------------------------------------- * * This struct holds arrays of individual attribute information * needed to create a tuple from raw C strings. It also requires * a copy of the TupleDesc. The information carried here * is derived from the TupleDesc, but it is stored here to * avoid redundant cpu cycles on each call to an SRF. */ typedef struct AttInMetadata { /* full TupleDesc */ TupleDesc tupdesc; /* array of attribute type input function finfo */ FmgrInfo *attinfuncs; /* array of attribute type i/o parameter OIDs */ Oid *attioparams; /* array of attribute typmod */ int32 *atttypmods; } AttInMetadata; /*------------------------------------------------------------------------- * Support struct to ease writing Set Returning Functions (SRFs) *------------------------------------------------------------------------- * * This struct holds function context for Set Returning Functions. * Use fn_extra to hold a pointer to it across calls */ typedef struct FuncCallContext { /* * Number of times we've been called before * * call_cntr is initialized to 0 for you by SRF_FIRSTCALL_INIT(), and * incremented for you every time SRF_RETURN_NEXT() is called. */ uint64 call_cntr; /* * OPTIONAL maximum number of calls * * max_calls is here for convenience only and setting it is optional. If * not set, you must provide alternative means to know when the function * is done. */ uint64 max_calls; /* * OPTIONAL pointer to miscellaneous user-provided context information * * user_fctx is for use as a pointer to your own struct to retain * arbitrary context information between calls of your function. */ void *user_fctx; /* * OPTIONAL pointer to struct containing attribute type input metadata * * attinmeta is for use when returning tuples (i.e. composite data types) * and is not used when returning base data types. It is only needed if * you intend to use BuildTupleFromCStrings() to create the return tuple. */ AttInMetadata *attinmeta; /* * memory context used for structures that must live for multiple calls * * multi_call_memory_ctx is set by SRF_FIRSTCALL_INIT() for you, and used * by SRF_RETURN_DONE() for cleanup. It is the most appropriate memory * context for any memory that is to be reused across multiple calls of * the SRF. */ MemoryContext multi_call_memory_ctx; /* * OPTIONAL pointer to struct containing tuple description * * tuple_desc is for use when returning tuples (i.e. composite data types) * and is only needed if you are going to build the tuples with * heap_form_tuple() rather than with BuildTupleFromCStrings(). Note that * the TupleDesc pointer stored here should usually have been run through * BlessTupleDesc() first. */ TupleDesc tuple_desc; } FuncCallContext; /*---------- * Support to ease writing functions returning composite types * * External declarations: * get_call_result_type: * Given a function's call info record, determine the kind of datatype * it is supposed to return. If resultTypeId isn't NULL, *resultTypeId * receives the actual datatype OID (this is mainly useful for scalar * result types). If resultTupleDesc isn't NULL, *resultTupleDesc * receives a pointer to a TupleDesc when the result is of a composite * type, or NULL when it's a scalar result or the rowtype could not be * determined. NB: the tupledesc should be copied if it is to be * accessed over a long period. * get_expr_result_type: * Given an expression node, return the same info as for * get_call_result_type. Note: the cases in which rowtypes cannot be * determined are different from the cases for get_call_result_type. * get_func_result_type: * Given only a function's OID, return the same info as for * get_call_result_type. Note: the cases in which rowtypes cannot be * determined are different from the cases for get_call_result_type. * Do *not* use this if you can use one of the others. * * See also get_expr_result_tupdesc(), which is a convenient wrapper around * get_expr_result_type() for use when the caller only cares about * determinable-rowtype cases. *---------- */ /* Type categories for get_call_result_type and siblings */ typedef enum TypeFuncClass { TYPEFUNC_SCALAR, /* scalar result type */ TYPEFUNC_COMPOSITE, /* determinable rowtype result */ TYPEFUNC_COMPOSITE_DOMAIN, /* domain over determinable rowtype result */ TYPEFUNC_RECORD, /* indeterminate rowtype result */ TYPEFUNC_OTHER, /* bogus type, eg pseudotype */ } TypeFuncClass; extern TypeFuncClass get_call_result_type(FunctionCallInfo fcinfo, Oid *resultTypeId, TupleDesc *resultTupleDesc); extern TypeFuncClass get_expr_result_type(Node *expr, Oid *resultTypeId, TupleDesc *resultTupleDesc); extern TypeFuncClass get_func_result_type(Oid functionId, Oid *resultTypeId, TupleDesc *resultTupleDesc); extern TupleDesc get_expr_result_tupdesc(Node *expr, bool noError); extern bool resolve_polymorphic_argtypes(int numargs, Oid *argtypes, char *argmodes, Node *call_expr); extern int get_func_arg_info(HeapTuple procTup, Oid **p_argtypes, char ***p_argnames, char **p_argmodes); extern int get_func_input_arg_names(Datum proargnames, Datum proargmodes, char ***arg_names); extern int get_func_trftypes(HeapTuple procTup, Oid **p_trftypes); extern char *get_func_result_name(Oid functionId); extern TupleDesc build_function_result_tupdesc_d(char prokind, Datum proallargtypes, Datum proargmodes, Datum proargnames); extern TupleDesc build_function_result_tupdesc_t(HeapTuple procTuple); /*---------- * Support to ease writing functions returning composite types * * External declarations: * TupleDesc BlessTupleDesc(TupleDesc tupdesc) - "Bless" a completed tuple * descriptor so that it can be used to return properly labeled tuples. * You need to call this if you are going to use heap_form_tuple directly. * TupleDescGetAttInMetadata does it for you, however, so no need to call * it if you call TupleDescGetAttInMetadata. * AttInMetadata *TupleDescGetAttInMetadata(TupleDesc tupdesc) - Build an * AttInMetadata struct based on the given TupleDesc. AttInMetadata can * be used in conjunction with C strings to produce a properly formed * tuple. * HeapTuple BuildTupleFromCStrings(AttInMetadata *attinmeta, char **values) - * build a HeapTuple given user data in C string form. values is an array * of C strings, one for each attribute of the return tuple. * Datum HeapTupleHeaderGetDatum(HeapTupleHeader tuple) - convert a * HeapTupleHeader to a Datum. * * Inline declarations: * HeapTupleGetDatum(HeapTuple tuple) - convert a HeapTuple to a Datum. * * Obsolete routines and macros: * TupleDesc RelationNameGetTupleDesc(const char *relname) - Use to get a * TupleDesc based on a named relation. * TupleDesc TypeGetTupleDesc(Oid typeoid, List *colaliases) - Use to get a * TupleDesc based on a type OID. * TupleGetDatum(TupleTableSlot *slot, HeapTuple tuple) - get a Datum * given a tuple and a slot. *---------- */ extern TupleDesc RelationNameGetTupleDesc(const char *relname); extern TupleDesc TypeGetTupleDesc(Oid typeoid, List *colaliases); /* from execTuples.c */ extern TupleDesc BlessTupleDesc(TupleDesc tupdesc); extern AttInMetadata *TupleDescGetAttInMetadata(TupleDesc tupdesc); extern HeapTuple BuildTupleFromCStrings(AttInMetadata *attinmeta, char **values); extern Datum HeapTupleHeaderGetDatum(HeapTupleHeader tuple); static inline Datum HeapTupleGetDatum(const HeapTupleData *tuple) { return HeapTupleHeaderGetDatum(tuple->t_data); } /* obsolete version of above */ #define TupleGetDatum(_slot, _tuple) HeapTupleGetDatum(_tuple) /*---------- * Support for Set Returning Functions (SRFs) * * The basic API for SRFs using ValuePerCall mode looks something like this: * * Datum * my_Set_Returning_Function(PG_FUNCTION_ARGS) * { * FuncCallContext *funcctx; * Datum result; * MemoryContext oldcontext; * * * if (SRF_IS_FIRSTCALL()) * { * funcctx = SRF_FIRSTCALL_INIT(); * // switch context when allocating stuff to be used in later calls * oldcontext = MemoryContextSwitchTo(funcctx->multi_call_memory_ctx); * * * * * * // return to original context when allocating transient memory * MemoryContextSwitchTo(oldcontext); * } * * funcctx = SRF_PERCALL_SETUP(); * * * if (funcctx->call_cntr < funcctx->max_calls) * { * * * SRF_RETURN_NEXT(funcctx, result); * } * else * SRF_RETURN_DONE(funcctx); * } * * NOTE: there is no guarantee that a SRF using ValuePerCall mode will be * run to completion; for example, a query with LIMIT might stop short of * fetching all the rows. Therefore, do not expect that you can do resource * cleanup just before SRF_RETURN_DONE(). You need not worry about releasing * memory allocated in multi_call_memory_ctx, but holding file descriptors or * other non-memory resources open across calls is a bug. SRFs that need * such resources should not use these macros, but instead populate a * tuplestore during a single call, as set up by InitMaterializedSRF() (see * fmgr/README). Alternatively, set up a callback to release resources * at query shutdown, using RegisterExprContextCallback(). * *---------- */ /* from funcapi.c */ /* flag bits for InitMaterializedSRF() */ #define MAT_SRF_USE_EXPECTED_DESC 0x01 /* use expectedDesc as tupdesc. */ #define MAT_SRF_BLESS 0x02 /* "Bless" a tuple descriptor with * BlessTupleDesc(). */ extern void InitMaterializedSRF(FunctionCallInfo fcinfo, bits32 flags); extern FuncCallContext *init_MultiFuncCall(PG_FUNCTION_ARGS); extern FuncCallContext *per_MultiFuncCall(PG_FUNCTION_ARGS); extern void end_MultiFuncCall(PG_FUNCTION_ARGS, FuncCallContext *funcctx); #define SRF_IS_FIRSTCALL() (fcinfo->flinfo->fn_extra == NULL) #define SRF_FIRSTCALL_INIT() init_MultiFuncCall(fcinfo) #define SRF_PERCALL_SETUP() per_MultiFuncCall(fcinfo) #define SRF_RETURN_NEXT(_funcctx, _result) \ do { \ ReturnSetInfo *rsi; \ (_funcctx)->call_cntr++; \ rsi = (ReturnSetInfo *) fcinfo->resultinfo; \ rsi->isDone = ExprMultipleResult; \ PG_RETURN_DATUM(_result); \ } while (0) #define SRF_RETURN_NEXT_NULL(_funcctx) \ do { \ ReturnSetInfo *rsi; \ (_funcctx)->call_cntr++; \ rsi = (ReturnSetInfo *) fcinfo->resultinfo; \ rsi->isDone = ExprMultipleResult; \ PG_RETURN_NULL(); \ } while (0) #define SRF_RETURN_DONE(_funcctx) \ do { \ ReturnSetInfo *rsi; \ end_MultiFuncCall(fcinfo, _funcctx); \ rsi = (ReturnSetInfo *) fcinfo->resultinfo; \ rsi->isDone = ExprEndResult; \ PG_RETURN_NULL(); \ } while (0) /*---------- * Support to ease writing of functions dealing with VARIADIC inputs *---------- * * This function extracts a set of argument values, types and NULL markers * for a given input function. This returns a set of data: * - **values includes the set of Datum values extracted. * - **types the data type OID for each element. * - **nulls tracks if an element is NULL. * * variadic_start indicates the argument number where the VARIADIC argument * starts. * convert_unknown set to true will enforce the conversion of arguments * with unknown data type to text. * * The return result is the number of elements stored, or -1 in the case of * "VARIADIC NULL". */ extern int extract_variadic_args(FunctionCallInfo fcinfo, int variadic_start, bool convert_unknown, Datum **args, Oid **types, bool **nulls); #endif /* FUNCAPI_H */