171 lines
6.5 KiB
C
171 lines
6.5 KiB
C
/*-------------------------------------------------------------------------
|
|
*
|
|
* params.h
|
|
* Support for finding the values associated with Param nodes.
|
|
*
|
|
*
|
|
* Portions Copyright (c) 1996-2024, 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 */
|