codekingpro/portable-devtools

1/*-------------------------------------------------------------------------2 *3 * funcapi.h4 *	  Definitions for functions which return composite type and/or sets5 *	  or work on VARIADIC inputs.6 *7 * This file must be included by all Postgres modules that either define8 * or call FUNCAPI-callable functions or macros.9 *10 *11 * Copyright (c) 2002-2023, PostgreSQL Global Development Group12 *13 * src/include/funcapi.h14 *15 *-------------------------------------------------------------------------16 */17#ifndef FUNCAPI_H18#define FUNCAPI_H19 20#include "access/tupdesc.h"21#include "executor/executor.h"22#include "executor/tuptable.h"23#include "fmgr.h"24 25/*-------------------------------------------------------------------------26 *	Support to ease writing Functions returning composite types27 *-------------------------------------------------------------------------28 *29 * This struct holds arrays of individual attribute information30 * needed to create a tuple from raw C strings. It also requires31 * a copy of the TupleDesc. The information carried here32 * is derived from the TupleDesc, but it is stored here to33 * avoid redundant cpu cycles on each call to an SRF.34 */35typedef struct AttInMetadata36{37	/* full TupleDesc */38	TupleDesc	tupdesc;39 40	/* array of attribute type input function finfo */41	FmgrInfo   *attinfuncs;42 43	/* array of attribute type i/o parameter OIDs */44	Oid		   *attioparams;45 46	/* array of attribute typmod */47	int32	   *atttypmods;48} AttInMetadata;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 calls56 */57typedef struct FuncCallContext58{59	/*60	 * Number of times we've been called before61	 *62	 * call_cntr is initialized to 0 for you by SRF_FIRSTCALL_INIT(), and63	 * incremented for you every time SRF_RETURN_NEXT() is called.64	 */65	uint64		call_cntr;66 67	/*68	 * OPTIONAL maximum number of calls69	 *70	 * max_calls is here for convenience only and setting it is optional. If71	 * not set, you must provide alternative means to know when the function72	 * is done.73	 */74	uint64		max_calls;75 76	/*77	 * OPTIONAL pointer to miscellaneous user-provided context information78	 *79	 * user_fctx is for use as a pointer to your own struct to retain80	 * arbitrary context information between calls of your function.81	 */82	void	   *user_fctx;83 84	/*85	 * OPTIONAL pointer to struct containing attribute type input metadata86	 *87	 * attinmeta is for use when returning tuples (i.e. composite data types)88	 * and is not used when returning base data types. It is only needed if89	 * you intend to use BuildTupleFromCStrings() to create the return tuple.90	 */91	AttInMetadata *attinmeta;92 93	/*94	 * memory context used for structures that must live for multiple calls95	 *96	 * multi_call_memory_ctx is set by SRF_FIRSTCALL_INIT() for you, and used97	 * by SRF_RETURN_DONE() for cleanup. It is the most appropriate memory98	 * context for any memory that is to be reused across multiple calls of99	 * the SRF.100	 */101	MemoryContext multi_call_memory_ctx;102 103	/*104	 * OPTIONAL pointer to struct containing tuple description105	 *106	 * tuple_desc is for use when returning tuples (i.e. composite data types)107	 * and is only needed if you are going to build the tuples with108	 * heap_form_tuple() rather than with BuildTupleFromCStrings(). Note that109	 * the TupleDesc pointer stored here should usually have been run through110	 * BlessTupleDesc() first.111	 */112	TupleDesc	tuple_desc;113 114} FuncCallContext;115 116/*----------117 *	Support to ease writing functions returning composite types118 *119 * External declarations:120 * get_call_result_type:121 *		Given a function's call info record, determine the kind of datatype122 *		it is supposed to return.  If resultTypeId isn't NULL, *resultTypeId123 *		receives the actual datatype OID (this is mainly useful for scalar124 *		result types).  If resultTupleDesc isn't NULL, *resultTupleDesc125 *		receives a pointer to a TupleDesc when the result is of a composite126 *		type, or NULL when it's a scalar result or the rowtype could not be127 *		determined.  NB: the tupledesc should be copied if it is to be128 *		accessed over a long period.129 * get_expr_result_type:130 *		Given an expression node, return the same info as for131 *		get_call_result_type.  Note: the cases in which rowtypes cannot be132 *		determined are different from the cases for get_call_result_type.133 * get_func_result_type:134 *		Given only a function's OID, return the same info as for135 *		get_call_result_type.  Note: the cases in which rowtypes cannot be136 *		determined are different from the cases for get_call_result_type.137 *		Do *not* use this if you can use one of the others.138 *139 * See also get_expr_result_tupdesc(), which is a convenient wrapper around140 * get_expr_result_type() for use when the caller only cares about141 * determinable-rowtype cases.142 *----------143 */144 145/* Type categories for get_call_result_type and siblings */146typedef enum TypeFuncClass147{148	TYPEFUNC_SCALAR,			/* scalar result type */149	TYPEFUNC_COMPOSITE,			/* determinable rowtype result */150	TYPEFUNC_COMPOSITE_DOMAIN,	/* domain over determinable rowtype result */151	TYPEFUNC_RECORD,			/* indeterminate rowtype result */152	TYPEFUNC_OTHER				/* bogus type, eg pseudotype */153} TypeFuncClass;154 155extern TypeFuncClass get_call_result_type(FunctionCallInfo fcinfo,156										  Oid *resultTypeId,157										  TupleDesc *resultTupleDesc);158extern TypeFuncClass get_expr_result_type(Node *expr,159										  Oid *resultTypeId,160										  TupleDesc *resultTupleDesc);161extern TypeFuncClass get_func_result_type(Oid functionId,162										  Oid *resultTypeId,163										  TupleDesc *resultTupleDesc);164 165extern TupleDesc get_expr_result_tupdesc(Node *expr, bool noError);166 167extern bool resolve_polymorphic_argtypes(int numargs, Oid *argtypes,168										 char *argmodes,169										 Node *call_expr);170 171extern int	get_func_arg_info(HeapTuple procTup,172							  Oid **p_argtypes, char ***p_argnames,173							  char **p_argmodes);174 175extern int	get_func_input_arg_names(Datum proargnames, Datum proargmodes,176									 char ***arg_names);177 178extern int	get_func_trftypes(HeapTuple procTup, Oid **p_trftypes);179extern char *get_func_result_name(Oid functionId);180 181extern TupleDesc build_function_result_tupdesc_d(char prokind,182												 Datum proallargtypes,183												 Datum proargmodes,184												 Datum proargnames);185extern TupleDesc build_function_result_tupdesc_t(HeapTuple procTuple);186 187 188/*----------189 *	Support to ease writing functions returning composite types190 *191 * External declarations:192 * TupleDesc BlessTupleDesc(TupleDesc tupdesc) - "Bless" a completed tuple193 *		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 call196 *		it if you call TupleDescGetAttInMetadata.197 * AttInMetadata *TupleDescGetAttInMetadata(TupleDesc tupdesc) - Build an198 *		AttInMetadata struct based on the given TupleDesc. AttInMetadata can199 *		be used in conjunction with C strings to produce a properly formed200 *		tuple.201 * HeapTuple BuildTupleFromCStrings(AttInMetadata *attinmeta, char **values) -202 *		build a HeapTuple given user data in C string form. values is an array203 *		of C strings, one for each attribute of the return tuple.204 * Datum HeapTupleHeaderGetDatum(HeapTupleHeader tuple) - convert a205 *		HeapTupleHeader to a Datum.206 *207 * Inline 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 a212 *		TupleDesc based on a named relation.213 * TupleDesc TypeGetTupleDesc(Oid typeoid, List *colaliases) - Use to get a214 *		TupleDesc based on a type OID.215 * TupleGetDatum(TupleTableSlot *slot, HeapTuple tuple) - get a Datum216 *		given a tuple and a slot.217 *----------218 */219 220extern TupleDesc RelationNameGetTupleDesc(const char *relname);221extern TupleDesc TypeGetTupleDesc(Oid typeoid, List *colaliases);222 223/* from execTuples.c */224extern TupleDesc BlessTupleDesc(TupleDesc tupdesc);225extern AttInMetadata *TupleDescGetAttInMetadata(TupleDesc tupdesc);226extern HeapTuple BuildTupleFromCStrings(AttInMetadata *attinmeta, char **values);227extern Datum HeapTupleHeaderGetDatum(HeapTupleHeader tuple);228 229static inline Datum230HeapTupleGetDatum(const HeapTupleData *tuple)231{232	return HeapTupleHeaderGetDatum(tuple->t_data);233}234 235/* obsolete version of above */236#define TupleGetDatum(_slot, _tuple)	HeapTupleGetDatum(_tuple)237 238 239/*----------240 *		Support for Set Returning Functions (SRFs)241 *242 * The basic API for SRFs using ValuePerCall mode looks something like this:243 *244 * Datum245 * my_Set_Returning_Function(PG_FUNCTION_ARGS)246 * {247 *	FuncCallContext    *funcctx;248 *	Datum				result;249 *	MemoryContext		oldcontext;250 *	<user defined declarations>251 *252 *	if (SRF_IS_FIRSTCALL())253 *	{254 *		funcctx = SRF_FIRSTCALL_INIT();255 *		// switch context when allocating stuff to be used in later calls256 *		oldcontext = MemoryContextSwitchTo(funcctx->multi_call_memory_ctx);257 *		<user defined code>258 *		<if returning composite>259 *			<build TupleDesc, and perhaps AttInMetadata>260 *		<endif returning composite>261 *		<user defined code>262 *		// return to original context when allocating transient memory263 *		MemoryContextSwitchTo(oldcontext);264 *	}265 *	<user defined code>266 *	funcctx = SRF_PERCALL_SETUP();267 *	<user defined code>268 *269 *	if (funcctx->call_cntr < funcctx->max_calls)270 *	{271 *		<user defined code>272 *		<obtain result Datum>273 *		SRF_RETURN_NEXT(funcctx, result);274 *	}275 *	else276 *		SRF_RETURN_DONE(funcctx);277 * }278 *279 * NOTE: there is no guarantee that a SRF using ValuePerCall mode will be280 * run to completion; for example, a query with LIMIT might stop short of281 * fetching all the rows.  Therefore, do not expect that you can do resource282 * cleanup just before SRF_RETURN_DONE().  You need not worry about releasing283 * memory allocated in multi_call_memory_ctx, but holding file descriptors or284 * other non-memory resources open across calls is a bug.  SRFs that need285 * such resources should not use these macros, but instead populate a286 * tuplestore during a single call, as set up by InitMaterializedSRF() (see287 * fmgr/README).  Alternatively, set up a callback to release resources288 * at query shutdown, using RegisterExprContextCallback().289 *290 *----------291 */292 293/* from funcapi.c */294 295/* flag bits for InitMaterializedSRF() */296#define MAT_SRF_USE_EXPECTED_DESC	0x01	/* use expectedDesc as tupdesc. */297#define MAT_SRF_BLESS				0x02	/* "Bless" a tuple descriptor with298											 * BlessTupleDesc(). */299extern void InitMaterializedSRF(FunctionCallInfo fcinfo, bits32 flags);300 301extern FuncCallContext *init_MultiFuncCall(PG_FUNCTION_ARGS);302extern FuncCallContext *per_MultiFuncCall(PG_FUNCTION_ARGS);303extern void end_MultiFuncCall(PG_FUNCTION_ARGS, FuncCallContext *funcctx);304 305#define SRF_IS_FIRSTCALL() (fcinfo->flinfo->fn_extra == NULL)306 307#define SRF_FIRSTCALL_INIT() init_MultiFuncCall(fcinfo)308 309#define SRF_PERCALL_SETUP() per_MultiFuncCall(fcinfo)310 311#define SRF_RETURN_NEXT(_funcctx, _result) \312	do { \313		ReturnSetInfo	   *rsi; \314		(_funcctx)->call_cntr++; \315		rsi = (ReturnSetInfo *) fcinfo->resultinfo; \316		rsi->isDone = ExprMultipleResult; \317		PG_RETURN_DATUM(_result); \318	} while (0)319 320#define SRF_RETURN_NEXT_NULL(_funcctx) \321	do { \322		ReturnSetInfo	   *rsi; \323		(_funcctx)->call_cntr++; \324		rsi = (ReturnSetInfo *) fcinfo->resultinfo; \325		rsi->isDone = ExprMultipleResult; \326		PG_RETURN_NULL(); \327	} while (0)328 329#define  SRF_RETURN_DONE(_funcctx) \330	do { \331		ReturnSetInfo	   *rsi; \332		end_MultiFuncCall(fcinfo, _funcctx); \333		rsi = (ReturnSetInfo *) fcinfo->resultinfo; \334		rsi->isDone = ExprEndResult; \335		PG_RETURN_NULL(); \336	} while (0)337 338/*----------339 *	Support to ease writing of functions dealing with VARIADIC inputs340 *----------341 *342 * This function extracts a set of argument values, types and NULL markers343 * for a given input function. This returns a set of data:344 * - **values includes the set of Datum values extracted.345 * - **types the data type OID for each element.346 * - **nulls tracks if an element is NULL.347 *348 * variadic_start indicates the argument number where the VARIADIC argument349 * starts.350 * convert_unknown set to true will enforce the conversion of arguments351 * with unknown data type to text.352 *353 * The return result is the number of elements stored, or -1 in the case of354 * "VARIADIC NULL".355 */356extern int	extract_variadic_args(FunctionCallInfo fcinfo, int variadic_start,357								  bool convert_unknown, Datum **args,358								  Oid **types, bool **nulls);359 360#endif							/* FUNCAPI_H */361