PostgreSQL Source Code  git master
params.h
Go to the documentation of this file.
1 /*-------------------------------------------------------------------------
2  *
3  * params.h
4  * Support for finding the values associated with Param nodes.
5  *
6  *
7  * Portions Copyright (c) 1996-2020, PostgreSQL Global Development Group
8  * Portions Copyright (c) 1994, Regents of the University of California
9  *
10  * src/include/nodes/params.h
11  *
12  *-------------------------------------------------------------------------
13  */
14 #ifndef PARAMS_H
15 #define PARAMS_H
16 
17 /* Forward declarations, to avoid including other headers */
18 struct Bitmapset;
19 struct ExprState;
20 struct Param;
21 struct ParseState;
22 
23 
24 /*
25  * ParamListInfo
26  *
27  * ParamListInfo structures are used to pass parameters into the executor
28  * for parameterized plans. We support two basic approaches to supplying
29  * parameter values, the "static" way and the "dynamic" way.
30  *
31  * In the static approach, per-parameter data is stored in an array of
32  * ParamExternData structs appended to the ParamListInfo struct.
33  * Each entry in the array defines the value to be substituted for a
34  * PARAM_EXTERN parameter. The "paramid" of a PARAM_EXTERN Param
35  * can range from 1 to numParams.
36  *
37  * Although parameter numbers are normally consecutive, we allow
38  * ptype == InvalidOid to signal an unused array entry.
39  *
40  * pflags is a flags field. Currently the only used bit is:
41  * PARAM_FLAG_CONST signals the planner that it may treat this parameter
42  * as a constant (i.e., generate a plan that works only for this value
43  * of the parameter).
44  *
45  * In the dynamic approach, all access to parameter values is done through
46  * hook functions found in the ParamListInfo struct. In this case,
47  * the ParamExternData array is typically unused and not allocated;
48  * but the legal range of paramid is still 1 to numParams.
49  *
50  * Although the data structure is really an array, not a list, we keep
51  * the old typedef name to avoid unnecessary code changes.
52  *
53  * There are 3 hook functions that can be associated with a ParamListInfo
54  * structure:
55  *
56  * If paramFetch isn't null, it is called to fetch the ParamExternData
57  * for a particular param ID, rather than accessing the relevant element
58  * of the ParamExternData array. This supports the case where the array
59  * isn't there at all, as well as cases where the data in the array
60  * might be obsolete or lazily evaluated. paramFetch must return the
61  * address of a ParamExternData struct describing the specified param ID;
62  * the convention above about ptype == InvalidOid signaling an invalid
63  * param ID still applies. The returned struct can either be placed in
64  * the "workspace" supplied by the caller, or it can be in storage
65  * controlled by the paramFetch hook if that's more convenient.
66  * (In either case, the struct is not expected to be long-lived.)
67  * If "speculative" is true, the paramFetch hook should not risk errors
68  * in trying to fetch the parameter value, and should report an invalid
69  * parameter instead.
70  *
71  * If paramCompile isn't null, then it controls what execExpr.c compiles
72  * for PARAM_EXTERN Param nodes --- typically, this hook would emit a
73  * EEOP_PARAM_CALLBACK step. This allows unnecessary work to be
74  * optimized away in compiled expressions.
75  *
76  * If parserSetup isn't null, then it is called to re-instantiate the
77  * original parsing hooks when a query needs to be re-parsed/planned.
78  * This is especially useful if the types of parameters might change
79  * from time to time, since it can replace the need to supply a fixed
80  * list of parameter types to the parser.
81  *
82  * Notice that the paramFetch and paramCompile hooks are actually passed
83  * the ParamListInfo struct's address; they can therefore access all
84  * three of the "arg" fields, and the distinction between paramFetchArg
85  * and paramCompileArg is rather arbitrary.
86  */
87 
88 #define PARAM_FLAG_CONST 0x0001 /* parameter is constant */
89 
90 typedef struct ParamExternData
91 {
92  Datum value; /* parameter value */
93  bool isnull; /* is it NULL? */
94  uint16 pflags; /* flag bits, see above */
95  Oid ptype; /* parameter's datatype, or 0 */
97 
99 
100 typedef ParamExternData *(*ParamFetchHook) (ParamListInfo params,
101  int paramid, bool speculative,
102  ParamExternData *workspace);
103 
104 typedef void (*ParamCompileHook) (ParamListInfo params, struct Param *param,
105  struct ExprState *state,
106  Datum *resv, bool *resnull);
107 
108 typedef void (*ParserSetupHook) (struct ParseState *pstate, void *arg);
109 
110 typedef struct ParamListInfoData
111 {
112  ParamFetchHook paramFetch; /* parameter fetch hook */
114  ParamCompileHook paramCompile; /* parameter compile hook */
116  ParserSetupHook parserSetup; /* parser setup hook */
118  char *paramValuesStr; /* params as a single string for errors */
119  int numParams; /* nominal/maximum # of Params represented */
120 
121  /*
122  * params[] may be of length zero if paramFetch is supplied; otherwise it
123  * must be of length numParams.
124  */
127 
128 
129 /* ----------------
130  * ParamExecData
131  *
132  * ParamExecData entries are used for executor internal parameters
133  * (that is, values being passed into or out of a sub-query). The
134  * paramid of a PARAM_EXEC Param is a (zero-based) index into an
135  * array of ParamExecData records, which is referenced through
136  * es_param_exec_vals or ecxt_param_exec_vals.
137  *
138  * If execPlan is not NULL, it points to a SubPlanState node that needs
139  * to be executed to produce the value. (This is done so that we can have
140  * lazy evaluation of InitPlans: they aren't executed until/unless a
141  * result value is needed.) Otherwise the value is assumed to be valid
142  * when needed.
143  * ----------------
144  */
145 
146 typedef struct ParamExecData
147 {
148  void *execPlan; /* should be "SubPlanState *" */
150  bool isnull;
151 } ParamExecData;
152 
153 /* type of argument for ParamsErrorCallback */
154 typedef struct ParamsErrorCbData
155 {
156  const char *portalName;
157  ParamListInfo params;
159 
160 /* Functions found in src/backend/nodes/params.c */
161 extern ParamListInfo makeParamList(int numParams);
162 extern ParamListInfo copyParamList(ParamListInfo from);
163 extern Size EstimateParamListSpace(ParamListInfo paramLI);
164 extern void SerializeParamList(ParamListInfo paramLI, char **start_address);
165 extern ParamListInfo RestoreParamList(char **start_address);
166 extern char *BuildParamLogString(ParamListInfo params, char **paramTextValues,
167  int valueLen);
168 extern void ParamsErrorCallback(void *arg);
169 
170 #endif /* PARAMS_H */
ParamExternData params[FLEXIBLE_ARRAY_MEMBER]
Definition: params.h:125
Datum value
Definition: params.h:92
void * execPlan
Definition: params.h:148
void * parserSetupArg
Definition: params.h:117
ParamListInfo params
Definition: params.h:157
void(* ParamCompileHook)(ParamListInfo params, struct Param *param, struct ExprState *state, Datum *resv, bool *resnull)
Definition: params.h:104
struct ParamsErrorCbData ParamsErrorCbData
#define FLEXIBLE_ARRAY_MEMBER
Definition: c.h:276
ParamListInfo copyParamList(ParamListInfo from)
Definition: params.c:69
ParserSetupHook parserSetup
Definition: params.h:116
struct ParamListInfoData * ParamListInfo
Definition: params.h:98
unsigned int Oid
Definition: postgres_ext.h:31
ParamListInfo RestoreParamList(char **start_address)
Definition: params.c:234
void * paramFetchArg
Definition: params.h:113
ParamCompileHook paramCompile
Definition: params.h:114
ParamFetchHook paramFetch
Definition: params.h:112
unsigned short uint16
Definition: c.h:366
bool resnull
Definition: execnodes.h:72
bool isnull
Definition: params.h:150
void(* ParserSetupHook)(struct ParseState *pstate, void *arg)
Definition: params.h:108
struct ParamListInfoData ParamListInfoData
ParamListInfo makeParamList(int numParams)
Definition: params.c:35
char * paramValuesStr
Definition: params.h:118
struct ParamExecData ParamExecData
struct ParamExternData ParamExternData
uintptr_t Datum
Definition: postgres.h:367
Size EstimateParamListSpace(ParamListInfo paramLI)
Definition: params.c:109
const char * portalName
Definition: params.h:156
Definition: regguts.h:298
void ParamsErrorCallback(void *arg)
Definition: params.c:349
uint16 pflags
Definition: params.h:94
size_t Size
Definition: c.h:466
void * paramCompileArg
Definition: params.h:115
Datum value
Definition: params.h:149
void * arg
ParamExternData *(* ParamFetchHook)(ParamListInfo params, int paramid, bool speculative, ParamExternData *workspace)
Definition: params.h:100
bool isnull
Definition: params.h:93
void SerializeParamList(ParamListInfo paramLI, char **start_address)
Definition: params.c:171
char * BuildParamLogString(ParamListInfo params, char **paramTextValues, int valueLen)
Definition: params.c:277