Age Owner TLA Line data Source code
1 : /*-------------------------------------------------------------------------
2 : *
3 : * nodes.h
4 : * Definitions for tagged nodes.
5 : *
6 : *
7 : * Portions Copyright (c) 1996-2023, PostgreSQL Global Development Group
8 : * Portions Copyright (c) 1994, Regents of the University of California
9 : *
10 : * src/include/nodes/nodes.h
11 : *
12 : *-------------------------------------------------------------------------
13 : */
14 : #ifndef NODES_H
15 : #define NODES_H
16 :
17 : /*
18 : * The first field of every node is NodeTag. Each node created (with makeNode)
19 : * will have one of the following tags as the value of its first field.
20 : *
21 : * Note that inserting or deleting node types changes the numbers of other
22 : * node types later in the list. This is no problem during development, since
23 : * the node numbers are never stored on disk. But don't do it in a released
24 : * branch, because that would represent an ABI break for extensions.
25 : */
26 : typedef enum NodeTag
27 : {
28 : T_Invalid = 0,
29 :
30 : #include "nodes/nodetags.h"
31 : } NodeTag;
32 :
33 : /*
34 : * pg_node_attr() - Used in node definitions to set extra information for
35 : * gen_node_support.pl
36 : *
37 : * Attributes can be attached to a node as a whole (place the attribute
38 : * specification on the first line after the struct's opening brace)
39 : * or to a specific field (place it at the end of that field's line). The
40 : * argument is a comma-separated list of attributes. Unrecognized attributes
41 : * cause an error.
42 : *
43 : * Valid node attributes:
44 : *
45 : * - abstract: Abstract types are types that cannot be instantiated but that
46 : * can be supertypes of other types. We track their fields, so that
47 : * subtypes can use them, but we don't emit a node tag, so you can't
48 : * instantiate them.
49 : *
50 : * - custom_copy_equal: Has custom implementations in copyfuncs.c and
51 : * equalfuncs.c.
52 : *
53 : * - custom_read_write: Has custom implementations in outfuncs.c and
54 : * readfuncs.c.
55 : *
56 : * - custom_query_jumble: Has custom implementation in queryjumblefuncs.c.
57 : *
58 : * - no_copy: Does not support copyObject() at all.
59 : *
60 : * - no_equal: Does not support equal() at all.
61 : *
62 : * - no_copy_equal: Shorthand for both no_copy and no_equal.
63 : *
64 : * - no_query_jumble: Does not support JumbleQuery() at all.
65 : *
66 : * - no_read: Does not support nodeRead() at all.
67 : *
68 : * - nodetag_only: Does not support copyObject(), equal(), jumbleQuery()
69 : * outNode() or nodeRead().
70 : *
71 : * - special_read_write: Has special treatment in outNode() and nodeRead().
72 : *
73 : * - nodetag_number(VALUE): assign the specified nodetag number instead of
74 : * an auto-generated number. Typically this would only be used in stable
75 : * branches, to give a newly-added node type a number without breaking ABI
76 : * by changing the numbers of existing node types.
77 : *
78 : * Node types can be supertypes of other types whether or not they are marked
79 : * abstract: if a node struct appears as the first field of another struct
80 : * type, then it is the supertype of that type. The no_copy, no_equal,
81 : * no_query_jumble and no_read node attributes are automatically inherited
82 : * from the supertype. (Notice that nodetag_only does not inherit, so it's
83 : * not quite equivalent to a combination of other attributes.)
84 : *
85 : * Valid node field attributes:
86 : *
87 : * - array_size(OTHERFIELD): This field is a dynamically allocated array with
88 : * size indicated by the mentioned other field. The other field is either a
89 : * scalar or a list, in which case the length of the list is used.
90 : *
91 : * - copy_as(VALUE): In copyObject(), replace the field's value with VALUE.
92 : *
93 : * - copy_as_scalar: In copyObject(), copy the field as a scalar value
94 : * (e.g. a pointer) even if it is a node-type pointer.
95 : *
96 : * - equal_as_scalar: In equal(), compare the field as a scalar value
97 : * even if it is a node-type pointer.
98 : *
99 : * - equal_ignore: Ignore the field for equality.
100 : *
101 : * - equal_ignore_if_zero: Ignore the field for equality if it is zero.
102 : * (Otherwise, compare normally.)
103 : *
104 : * - query_jumble_ignore: Ignore the field for the query jumbling. Note
105 : * that typmod and collation information are usually irrelevant for the
106 : * query jumbling.
107 : *
108 : * - query_jumble_location: Mark the field as a location to track. This is
109 : * only allowed for integer fields that include "location" in their name.
110 : *
111 : * - read_as(VALUE): In nodeRead(), replace the field's value with VALUE.
112 : *
113 : * - read_write_ignore: Ignore the field for read/write. This is only allowed
114 : * if the node type is marked no_read or read_as() is also specified.
115 : *
116 : * - write_only_relids, write_only_nondefault_pathtarget, write_only_req_outer:
117 : * Special handling for Path struct; see there.
118 : *
119 : */
120 : #define pg_node_attr(...)
121 :
122 : /*
123 : * The first field of a node of any type is guaranteed to be the NodeTag.
124 : * Hence the type of any node can be gotten by casting it to Node. Declaring
125 : * a variable to be of Node * (instead of void *) can also facilitate
126 : * debugging.
127 : */
128 : typedef struct Node
129 : {
130 : NodeTag type;
131 : } Node;
132 :
133 : #define nodeTag(nodeptr) (((const Node*)(nodeptr))->type)
134 :
135 : /*
136 : * newNode -
137 : * create a new node of the specified size and tag the node with the
138 : * specified tag.
139 : *
140 : * !WARNING!: Avoid using newNode directly. You should be using the
141 : * macro makeNode. eg. to create a Query node, use makeNode(Query)
142 : *
143 : * Note: the size argument should always be a compile-time constant, so the
144 : * apparent risk of multiple evaluation doesn't matter in practice.
145 : */
146 : #ifdef __GNUC__
147 :
148 : /* With GCC, we can use a compound statement within an expression */
149 : #define newNode(size, tag) \
150 : ({ Node *_result; \
151 : AssertMacro((size) >= sizeof(Node)); /* need the tag, at least */ \
152 : _result = (Node *) palloc0fast(size); \
153 : _result->type = (tag); \
154 : _result; \
155 : })
156 : #else
157 :
158 : /*
159 : * There is no way to dereference the palloc'ed pointer to assign the
160 : * tag, and also return the pointer itself, so we need a holder variable.
161 : * Fortunately, this macro isn't recursive so we just define
162 : * a global variable for this purpose.
163 : */
164 : extern PGDLLIMPORT Node *newNodeMacroHolder;
165 :
166 : #define newNode(size, tag) \
167 : ( \
168 : AssertMacro((size) >= sizeof(Node)), /* need the tag, at least */ \
169 : newNodeMacroHolder = (Node *) palloc0fast(size), \
170 : newNodeMacroHolder->type = (tag), \
171 : newNodeMacroHolder \
172 : )
173 : #endif /* __GNUC__ */
174 :
175 :
176 : #define makeNode(_type_) ((_type_ *) newNode(sizeof(_type_),T_##_type_))
177 : #define NodeSetTag(nodeptr,t) (((Node*)(nodeptr))->type = (t))
178 :
179 : #define IsA(nodeptr,_type_) (nodeTag(nodeptr) == T_##_type_)
180 :
181 : /*
182 : * castNode(type, ptr) casts ptr to "type *", and if assertions are enabled,
183 : * verifies that the node has the appropriate type (using its nodeTag()).
184 : *
185 : * Use an inline function when assertions are enabled, to avoid multiple
186 : * evaluations of the ptr argument (which could e.g. be a function call).
187 : */
188 : #ifdef USE_ASSERT_CHECKING
189 : static inline Node *
2263 tgl 190 GIC 152851044 : castNodeImpl(NodeTag type, void *ptr)
191 : {
2264 andres 192 152851044 : Assert(ptr == NULL || nodeTag(ptr) == type);
2263 tgl 193 152851044 : return (Node *) ptr;
194 : }
195 : #define castNode(_type_, nodeptr) ((_type_ *) castNodeImpl(T_##_type_, nodeptr))
196 : #else
197 : #define castNode(_type_, nodeptr) ((_type_ *) (nodeptr))
198 : #endif /* USE_ASSERT_CHECKING */
199 :
200 :
201 : /* ----------------------------------------------------------------
202 : * extern declarations follow
203 : * ----------------------------------------------------------------
204 : */
205 :
206 : /*
207 : * nodes/{outfuncs.c,print.c}
208 : */
209 : struct Bitmapset; /* not to include bitmapset.h here */
210 : struct StringInfoData; /* not to include stringinfo.h here */
211 :
212 : extern void outNode(struct StringInfoData *str, const void *obj);
213 : extern void outToken(struct StringInfoData *str, const char *s);
214 : extern void outBitmapset(struct StringInfoData *str,
215 : const struct Bitmapset *bms);
216 : extern void outDatum(struct StringInfoData *str, uintptr_t value,
217 : int typlen, bool typbyval);
218 : extern char *nodeToString(const void *obj);
219 : extern char *bmsToString(const struct Bitmapset *bms);
220 :
221 : /*
222 : * nodes/{readfuncs.c,read.c}
223 : */
224 : extern void *stringToNode(const char *str);
225 : #ifdef WRITE_READ_PARSE_PLAN_TREES
226 : extern void *stringToNodeWithLocations(const char *str);
227 : #endif
228 : extern struct Bitmapset *readBitmapset(void);
229 : extern uintptr_t readDatum(bool typbyval);
230 : extern bool *readBoolCols(int numCols);
231 : extern int *readIntCols(int numCols);
232 : extern Oid *readOidCols(int numCols);
233 : extern int16 *readAttrNumberCols(int numCols);
234 :
235 : /*
236 : * nodes/copyfuncs.c
237 : */
238 : extern void *copyObjectImpl(const void *from);
239 :
240 : /* cast result back to argument type, if supported by compiler */
241 : #ifdef HAVE_TYPEOF
242 : #define copyObject(obj) ((typeof(obj)) copyObjectImpl(obj))
243 : #else
244 : #define copyObject(obj) copyObjectImpl(obj)
245 : #endif
246 :
247 : /*
248 : * nodes/equalfuncs.c
249 : */
250 : extern bool equal(const void *a, const void *b);
251 :
252 :
253 : /*
254 : * Typedefs for identifying qualifier selectivities and plan costs as such.
255 : * These are just plain "double"s, but declaring a variable as Selectivity
256 : * or Cost makes the intent more obvious.
257 : *
258 : * These could have gone into plannodes.h or some such, but many files
259 : * depend on them...
260 : */
261 : typedef double Selectivity; /* fraction of tuples a qualifier will pass */
262 : typedef double Cost; /* execution cost (in page-access units) */
263 : typedef double Cardinality; /* (estimated) number of rows or other integer
264 : * count */
265 :
266 :
267 : /*
268 : * CmdType -
269 : * enums for type of operation represented by a Query or PlannedStmt
270 : *
271 : * This is needed in both parsenodes.h and plannodes.h, so put it here...
272 : */
273 : typedef enum CmdType
274 : {
275 : CMD_UNKNOWN,
276 : CMD_SELECT, /* select stmt */
277 : CMD_UPDATE, /* update stmt */
278 : CMD_INSERT, /* insert stmt */
279 : CMD_DELETE, /* delete stmt */
280 : CMD_MERGE, /* merge stmt */
281 : CMD_UTILITY, /* cmds like create, destroy, copy, vacuum,
282 : * etc. */
283 : CMD_NOTHING /* dummy command for instead nothing rules
284 : * with qual */
285 : } CmdType;
286 :
287 :
288 : /*
289 : * JoinType -
290 : * enums for types of relation joins
291 : *
292 : * JoinType determines the exact semantics of joining two relations using
293 : * a matching qualification. For example, it tells what to do with a tuple
294 : * that has no match in the other relation.
295 : *
296 : * This is needed in both parsenodes.h and plannodes.h, so put it here...
297 : */
298 : typedef enum JoinType
299 : {
300 : /*
301 : * The canonical kinds of joins according to the SQL JOIN syntax. Only
302 : * these codes can appear in parser output (e.g., JoinExpr nodes).
303 : */
304 : JOIN_INNER, /* matching tuple pairs only */
305 : JOIN_LEFT, /* pairs + unmatched LHS tuples */
306 : JOIN_FULL, /* pairs + unmatched LHS + unmatched RHS */
307 : JOIN_RIGHT, /* pairs + unmatched RHS tuples */
308 :
309 : /*
310 : * Semijoins and anti-semijoins (as defined in relational theory) do not
311 : * appear in the SQL JOIN syntax, but there are standard idioms for
312 : * representing them (e.g., using EXISTS). The planner recognizes these
313 : * cases and converts them to joins. So the planner and executor must
314 : * support these codes. NOTE: in JOIN_SEMI output, it is unspecified
315 : * which matching RHS row is joined to. In JOIN_ANTI output, the row is
316 : * guaranteed to be null-extended.
317 : */
318 : JOIN_SEMI, /* 1 copy of each LHS row that has match(es) */
319 : JOIN_ANTI, /* 1 copy of each LHS row that has no match */
320 : JOIN_RIGHT_ANTI, /* 1 copy of each RHS row that has no match */
321 :
322 : /*
323 : * These codes are used internally in the planner, but are not supported
324 : * by the executor (nor, indeed, by most of the planner).
325 : */
326 : JOIN_UNIQUE_OUTER, /* LHS path must be made unique */
327 : JOIN_UNIQUE_INNER /* RHS path must be made unique */
328 :
329 : /*
330 : * We might need additional join types someday.
331 : */
332 : } JoinType;
333 :
334 : /*
335 : * OUTER joins are those for which pushed-down quals must behave differently
336 : * from the join's own quals. This is in fact everything except INNER and
337 : * SEMI joins. However, this macro must also exclude the JOIN_UNIQUE symbols
338 : * since those are temporary proxies for what will eventually be an INNER
339 : * join.
340 : *
341 : * Note: semijoins are a hybrid case, but we choose to treat them as not
342 : * being outer joins. This is okay principally because the SQL syntax makes
343 : * it impossible to have a pushed-down qual that refers to the inner relation
344 : * of a semijoin; so there is no strong need to distinguish join quals from
345 : * pushed-down quals. This is convenient because for almost all purposes,
346 : * quals attached to a semijoin can be treated the same as innerjoin quals.
347 : */
348 : #define IS_OUTER_JOIN(jointype) \
349 : (((1 << (jointype)) & \
350 : ((1 << JOIN_LEFT) | \
351 : (1 << JOIN_FULL) | \
352 : (1 << JOIN_RIGHT) | \
353 : (1 << JOIN_ANTI) | \
354 : (1 << JOIN_RIGHT_ANTI))) != 0)
355 :
356 : /*
357 : * AggStrategy -
358 : * overall execution strategies for Agg plan nodes
359 : *
360 : * This is needed in both pathnodes.h and plannodes.h, so put it here...
361 : */
362 : typedef enum AggStrategy
363 : {
364 : AGG_PLAIN, /* simple agg across all input rows */
365 : AGG_SORTED, /* grouped agg, input must be sorted */
366 : AGG_HASHED, /* grouped agg, use internal hashtable */
367 : AGG_MIXED /* grouped agg, hash and sort both used */
368 : } AggStrategy;
369 :
370 : /*
371 : * AggSplit -
372 : * splitting (partial aggregation) modes for Agg plan nodes
373 : *
374 : * This is needed in both pathnodes.h and plannodes.h, so put it here...
375 : */
376 :
377 : /* Primitive options supported by nodeAgg.c: */
378 : #define AGGSPLITOP_COMBINE 0x01 /* substitute combinefn for transfn */
379 : #define AGGSPLITOP_SKIPFINAL 0x02 /* skip finalfn, return state as-is */
380 : #define AGGSPLITOP_SERIALIZE 0x04 /* apply serialfn to output */
381 : #define AGGSPLITOP_DESERIALIZE 0x08 /* apply deserialfn to input */
382 :
383 : /* Supported operating modes (i.e., useful combinations of these options): */
384 : typedef enum AggSplit
385 : {
386 : /* Basic, non-split aggregation: */
387 : AGGSPLIT_SIMPLE = 0,
388 : /* Initial phase of partial aggregation, with serialization: */
389 : AGGSPLIT_INITIAL_SERIAL = AGGSPLITOP_SKIPFINAL | AGGSPLITOP_SERIALIZE,
390 : /* Final phase of partial aggregation, with deserialization: */
391 : AGGSPLIT_FINAL_DESERIAL = AGGSPLITOP_COMBINE | AGGSPLITOP_DESERIALIZE
392 : } AggSplit;
393 :
394 : /* Test whether an AggSplit value selects each primitive option: */
395 : #define DO_AGGSPLIT_COMBINE(as) (((as) & AGGSPLITOP_COMBINE) != 0)
396 : #define DO_AGGSPLIT_SKIPFINAL(as) (((as) & AGGSPLITOP_SKIPFINAL) != 0)
397 : #define DO_AGGSPLIT_SERIALIZE(as) (((as) & AGGSPLITOP_SERIALIZE) != 0)
398 : #define DO_AGGSPLIT_DESERIALIZE(as) (((as) & AGGSPLITOP_DESERIALIZE) != 0)
399 :
400 : /*
401 : * SetOpCmd and SetOpStrategy -
402 : * overall semantics and execution strategies for SetOp plan nodes
403 : *
404 : * This is needed in both pathnodes.h and plannodes.h, so put it here...
405 : */
406 : typedef enum SetOpCmd
407 : {
408 : SETOPCMD_INTERSECT,
409 : SETOPCMD_INTERSECT_ALL,
410 : SETOPCMD_EXCEPT,
411 : SETOPCMD_EXCEPT_ALL
412 : } SetOpCmd;
413 :
414 : typedef enum SetOpStrategy
415 : {
416 : SETOP_SORTED, /* input must be sorted */
417 : SETOP_HASHED /* use internal hashtable */
418 : } SetOpStrategy;
419 :
420 : /*
421 : * OnConflictAction -
422 : * "ON CONFLICT" clause type of query
423 : *
424 : * This is needed in both parsenodes.h and plannodes.h, so put it here...
425 : */
426 : typedef enum OnConflictAction
427 : {
428 : ONCONFLICT_NONE, /* No "ON CONFLICT" clause */
429 : ONCONFLICT_NOTHING, /* ON CONFLICT ... DO NOTHING */
430 : ONCONFLICT_UPDATE /* ON CONFLICT ... DO UPDATE */
431 : } OnConflictAction;
432 :
433 : /*
434 : * LimitOption -
435 : * LIMIT option of query
436 : *
437 : * This is needed in both parsenodes.h and plannodes.h, so put it here...
438 : */
439 : typedef enum LimitOption
440 : {
441 : LIMIT_OPTION_COUNT, /* FETCH FIRST... ONLY */
442 : LIMIT_OPTION_WITH_TIES, /* FETCH FIRST... WITH TIES */
443 : LIMIT_OPTION_DEFAULT, /* No limit present */
444 : } LimitOption;
445 :
446 : #endif /* NODES_H */
|
