diff options
Diffstat (limited to 'src/include/nodes/params.h')
| -rw-r--r-- | src/include/nodes/params.h | 170 |
1 files changed, 170 insertions, 0 deletions
diff --git a/src/include/nodes/params.h b/src/include/nodes/params.h new file mode 100644 index 0000000..ad23113 --- /dev/null +++ b/src/include/nodes/params.h @@ -0,0 +1,170 @@ +/*------------------------------------------------------------------------- + * + * params.h + * Support for finding the values associated with Param nodes. + * + * + * Portions Copyright (c) 1996-2023, PostgreSQL Global Development Group + * Portions Copyright (c) 1994, Regents of the University of California + * + * src/include/nodes/params.h + * + *------------------------------------------------------------------------- + */ +#ifndef PARAMS_H +#define PARAMS_H + +/* Forward declarations, to avoid including other headers */ +struct Bitmapset; +struct ExprState; +struct Param; +struct ParseState; + + +/* + * ParamListInfo + * + * ParamListInfo structures are used to pass parameters into the executor + * for parameterized plans. We support two basic approaches to supplying + * parameter values, the "static" way and the "dynamic" way. + * + * In the static approach, per-parameter data is stored in an array of + * ParamExternData structs appended to the ParamListInfo struct. + * Each entry in the array defines the value to be substituted for a + * PARAM_EXTERN parameter. The "paramid" of a PARAM_EXTERN Param + * can range from 1 to numParams. + * + * Although parameter numbers are normally consecutive, we allow + * ptype == InvalidOid to signal an unused array entry. + * + * pflags is a flags field. Currently the only used bit is: + * PARAM_FLAG_CONST signals the planner that it may treat this parameter + * as a constant (i.e., generate a plan that works only for this value + * of the parameter). + * + * In the dynamic approach, all access to parameter values is done through + * hook functions found in the ParamListInfo struct. In this case, + * the ParamExternData array is typically unused and not allocated; + * but the legal range of paramid is still 1 to numParams. + * + * Although the data structure is really an array, not a list, we keep + * the old typedef name to avoid unnecessary code changes. + * + * There are 3 hook functions that can be associated with a ParamListInfo + * structure: + * + * If paramFetch isn't null, it is called to fetch the ParamExternData + * for a particular param ID, rather than accessing the relevant element + * of the ParamExternData array. This supports the case where the array + * isn't there at all, as well as cases where the data in the array + * might be obsolete or lazily evaluated. paramFetch must return the + * address of a ParamExternData struct describing the specified param ID; + * the convention above about ptype == InvalidOid signaling an invalid + * param ID still applies. The returned struct can either be placed in + * the "workspace" supplied by the caller, or it can be in storage + * controlled by the paramFetch hook if that's more convenient. + * (In either case, the struct is not expected to be long-lived.) + * If "speculative" is true, the paramFetch hook should not risk errors + * in trying to fetch the parameter value, and should report an invalid + * parameter instead. + * + * If paramCompile isn't null, then it controls what execExpr.c compiles + * for PARAM_EXTERN Param nodes --- typically, this hook would emit a + * EEOP_PARAM_CALLBACK step. This allows unnecessary work to be + * optimized away in compiled expressions. + * + * If parserSetup isn't null, then it is called to re-instantiate the + * original parsing hooks when a query needs to be re-parsed/planned. + * This is especially useful if the types of parameters might change + * from time to time, since it can replace the need to supply a fixed + * list of parameter types to the parser. + * + * Notice that the paramFetch and paramCompile hooks are actually passed + * the ParamListInfo struct's address; they can therefore access all + * three of the "arg" fields, and the distinction between paramFetchArg + * and paramCompileArg is rather arbitrary. + */ + +#define PARAM_FLAG_CONST 0x0001 /* parameter is constant */ + +typedef struct ParamExternData +{ + Datum value; /* parameter value */ + bool isnull; /* is it NULL? */ + uint16 pflags; /* flag bits, see above */ + Oid ptype; /* parameter's datatype, or 0 */ +} ParamExternData; + +typedef struct ParamListInfoData *ParamListInfo; + +typedef ParamExternData *(*ParamFetchHook) (ParamListInfo params, + int paramid, bool speculative, + ParamExternData *workspace); + +typedef void (*ParamCompileHook) (ParamListInfo params, struct Param *param, + struct ExprState *state, + Datum *resv, bool *resnull); + +typedef void (*ParserSetupHook) (struct ParseState *pstate, void *arg); + +typedef struct ParamListInfoData +{ + ParamFetchHook paramFetch; /* parameter fetch hook */ + void *paramFetchArg; + ParamCompileHook paramCompile; /* parameter compile hook */ + void *paramCompileArg; + ParserSetupHook parserSetup; /* parser setup hook */ + void *parserSetupArg; + char *paramValuesStr; /* params as a single string for errors */ + int numParams; /* nominal/maximum # of Params represented */ + + /* + * params[] may be of length zero if paramFetch is supplied; otherwise it + * must be of length numParams. + */ + ParamExternData params[FLEXIBLE_ARRAY_MEMBER]; +} ParamListInfoData; + + +/* ---------------- + * ParamExecData + * + * ParamExecData entries are used for executor internal parameters + * (that is, values being passed into or out of a sub-query). The + * paramid of a PARAM_EXEC Param is a (zero-based) index into an + * array of ParamExecData records, which is referenced through + * es_param_exec_vals or ecxt_param_exec_vals. + * + * If execPlan is not NULL, it points to a SubPlanState node that needs + * to be executed to produce the value. (This is done so that we can have + * lazy evaluation of InitPlans: they aren't executed until/unless a + * result value is needed.) Otherwise the value is assumed to be valid + * when needed. + * ---------------- + */ + +typedef struct ParamExecData +{ + void *execPlan; /* should be "SubPlanState *" */ + Datum value; + bool isnull; +} ParamExecData; + +/* type of argument for ParamsErrorCallback */ +typedef struct ParamsErrorCbData +{ + const char *portalName; + ParamListInfo params; +} ParamsErrorCbData; + +/* Functions found in src/backend/nodes/params.c */ +extern ParamListInfo makeParamList(int numParams); +extern ParamListInfo copyParamList(ParamListInfo from); +extern Size EstimateParamListSpace(ParamListInfo paramLI); +extern void SerializeParamList(ParamListInfo paramLI, char **start_address); +extern ParamListInfo RestoreParamList(char **start_address); +extern char *BuildParamLogString(ParamListInfo params, char **knownTextValues, + int maxlen); +extern void ParamsErrorCallback(void *arg); + +#endif /* PARAMS_H */ |