Age Owner Branch data TLA Line data Source code
1 : : /*-------------------------------------------------------------------------
2 : : *
3 : : * nodes.h
4 : : * Definitions for tagged nodes.
5 : : *
6 : : *
7 : : * Portions Copyright (c) 1996-2024, 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 : : static inline Node *
117 heikki.linnakangas@i 144 :GNC 53190359 : newNode(size_t size, NodeTag tag)
145 : : {
146 : : Node *result;
147 : :
148 [ - + ]: 53190359 : Assert(size >= sizeof(Node)); /* need the tag, at least */
149 : 53190359 : result = (Node *) palloc0(size);
150 : 53190359 : result->type = tag;
151 : :
152 : 53190359 : return result;
153 : : }
154 : :
155 : : #define makeNode(_type_) ((_type_ *) newNode(sizeof(_type_),T_##_type_))
156 : : #define NodeSetTag(nodeptr,t) (((Node*)(nodeptr))->type = (t))
157 : :
158 : : #define IsA(nodeptr,_type_) (nodeTag(nodeptr) == T_##_type_)
159 : :
160 : : /*
161 : : * castNode(type, ptr) casts ptr to "type *", and if assertions are enabled,
162 : : * verifies that the node has the appropriate type (using its nodeTag()).
163 : : *
164 : : * Use an inline function when assertions are enabled, to avoid multiple
165 : : * evaluations of the ptr argument (which could e.g. be a function call).
166 : : */
167 : : #ifdef USE_ASSERT_CHECKING
168 : : static inline Node *
2634 tgl@sss.pgh.pa.us 169 :CBC 124411577 : castNodeImpl(NodeTag type, void *ptr)
170 : : {
2635 andres@anarazel.de 171 [ + + - + ]: 124411577 : Assert(ptr == NULL || nodeTag(ptr) == type);
2634 tgl@sss.pgh.pa.us 172 : 124411577 : return (Node *) ptr;
173 : : }
174 : : #define castNode(_type_, nodeptr) ((_type_ *) castNodeImpl(T_##_type_, nodeptr))
175 : : #else
176 : : #define castNode(_type_, nodeptr) ((_type_ *) (nodeptr))
177 : : #endif /* USE_ASSERT_CHECKING */
178 : :
179 : :
180 : : /* ----------------------------------------------------------------
181 : : * extern declarations follow
182 : : * ----------------------------------------------------------------
183 : : */
184 : :
185 : : /*
186 : : * nodes/{outfuncs.c,print.c}
187 : : */
188 : : struct Bitmapset; /* not to include bitmapset.h here */
189 : : struct StringInfoData; /* not to include stringinfo.h here */
190 : :
191 : : extern void outNode(struct StringInfoData *str, const void *obj);
192 : : extern void outToken(struct StringInfoData *str, const char *s);
193 : : extern void outBitmapset(struct StringInfoData *str,
194 : : const struct Bitmapset *bms);
195 : : extern void outDatum(struct StringInfoData *str, uintptr_t value,
196 : : int typlen, bool typbyval);
197 : : extern char *nodeToString(const void *obj);
198 : : extern char *nodeToStringWithLocations(const void *obj);
199 : : extern char *bmsToString(const struct Bitmapset *bms);
200 : :
201 : : /*
202 : : * nodes/{readfuncs.c,read.c}
203 : : */
204 : : extern void *stringToNode(const char *str);
205 : : #ifdef WRITE_READ_PARSE_PLAN_TREES
206 : : extern void *stringToNodeWithLocations(const char *str);
207 : : #endif
208 : : extern struct Bitmapset *readBitmapset(void);
209 : : extern uintptr_t readDatum(bool typbyval);
210 : : extern bool *readBoolCols(int numCols);
211 : : extern int *readIntCols(int numCols);
212 : : extern Oid *readOidCols(int numCols);
213 : : extern int16 *readAttrNumberCols(int numCols);
214 : :
215 : : /*
216 : : * nodes/copyfuncs.c
217 : : */
218 : : extern void *copyObjectImpl(const void *from);
219 : :
220 : : /* cast result back to argument type, if supported by compiler */
221 : : #ifdef HAVE_TYPEOF
222 : : #define copyObject(obj) ((typeof(obj)) copyObjectImpl(obj))
223 : : #else
224 : : #define copyObject(obj) copyObjectImpl(obj)
225 : : #endif
226 : :
227 : : /*
228 : : * nodes/equalfuncs.c
229 : : */
230 : : extern bool equal(const void *a, const void *b);
231 : :
232 : :
233 : : /*
234 : : * Typedef for parse location. This is just an int, but this way
235 : : * gen_node_support.pl knows which fields should get special treatment for
236 : : * location values.
237 : : *
238 : : * -1 is used for unknown.
239 : : */
240 : : typedef int ParseLoc;
241 : :
242 : : /*
243 : : * Typedefs for identifying qualifier selectivities, plan costs, and row
244 : : * counts as such. These are just plain "double"s, but declaring a variable
245 : : * as Selectivity, Cost, or Cardinality makes the intent more obvious.
246 : : *
247 : : * These could have gone into plannodes.h or some such, but many files
248 : : * depend on them...
249 : : */
250 : : typedef double Selectivity; /* fraction of tuples a qualifier will pass */
251 : : typedef double Cost; /* execution cost (in page-access units) */
252 : : typedef double Cardinality; /* (estimated) number of rows or other integer
253 : : * count */
254 : :
255 : :
256 : : /*
257 : : * CmdType -
258 : : * enums for type of operation represented by a Query or PlannedStmt
259 : : *
260 : : * This is needed in both parsenodes.h and plannodes.h, so put it here...
261 : : */
262 : : typedef enum CmdType
263 : : {
264 : : CMD_UNKNOWN,
265 : : CMD_SELECT, /* select stmt */
266 : : CMD_UPDATE, /* update stmt */
267 : : CMD_INSERT, /* insert stmt */
268 : : CMD_DELETE, /* delete stmt */
269 : : CMD_MERGE, /* merge stmt */
270 : : CMD_UTILITY, /* cmds like create, destroy, copy, vacuum,
271 : : * etc. */
272 : : CMD_NOTHING, /* dummy command for instead nothing rules
273 : : * with qual */
274 : : } CmdType;
275 : :
276 : :
277 : : /*
278 : : * JoinType -
279 : : * enums for types of relation joins
280 : : *
281 : : * JoinType determines the exact semantics of joining two relations using
282 : : * a matching qualification. For example, it tells what to do with a tuple
283 : : * that has no match in the other relation.
284 : : *
285 : : * This is needed in both parsenodes.h and plannodes.h, so put it here...
286 : : */
287 : : typedef enum JoinType
288 : : {
289 : : /*
290 : : * The canonical kinds of joins according to the SQL JOIN syntax. Only
291 : : * these codes can appear in parser output (e.g., JoinExpr nodes).
292 : : */
293 : : JOIN_INNER, /* matching tuple pairs only */
294 : : JOIN_LEFT, /* pairs + unmatched LHS tuples */
295 : : JOIN_FULL, /* pairs + unmatched LHS + unmatched RHS */
296 : : JOIN_RIGHT, /* pairs + unmatched RHS tuples */
297 : :
298 : : /*
299 : : * Semijoins and anti-semijoins (as defined in relational theory) do not
300 : : * appear in the SQL JOIN syntax, but there are standard idioms for
301 : : * representing them (e.g., using EXISTS). The planner recognizes these
302 : : * cases and converts them to joins. So the planner and executor must
303 : : * support these codes. NOTE: in JOIN_SEMI output, it is unspecified
304 : : * which matching RHS row is joined to. In JOIN_ANTI output, the row is
305 : : * guaranteed to be null-extended.
306 : : */
307 : : JOIN_SEMI, /* 1 copy of each LHS row that has match(es) */
308 : : JOIN_ANTI, /* 1 copy of each LHS row that has no match */
309 : : JOIN_RIGHT_ANTI, /* 1 copy of each RHS row that has no match */
310 : :
311 : : /*
312 : : * These codes are used internally in the planner, but are not supported
313 : : * by the executor (nor, indeed, by most of the planner).
314 : : */
315 : : JOIN_UNIQUE_OUTER, /* LHS path must be made unique */
316 : : JOIN_UNIQUE_INNER, /* RHS path must be made unique */
317 : :
318 : : /*
319 : : * We might need additional join types someday.
320 : : */
321 : : } JoinType;
322 : :
323 : : /*
324 : : * OUTER joins are those for which pushed-down quals must behave differently
325 : : * from the join's own quals. This is in fact everything except INNER and
326 : : * SEMI joins. However, this macro must also exclude the JOIN_UNIQUE symbols
327 : : * since those are temporary proxies for what will eventually be an INNER
328 : : * join.
329 : : *
330 : : * Note: semijoins are a hybrid case, but we choose to treat them as not
331 : : * being outer joins. This is okay principally because the SQL syntax makes
332 : : * it impossible to have a pushed-down qual that refers to the inner relation
333 : : * of a semijoin; so there is no strong need to distinguish join quals from
334 : : * pushed-down quals. This is convenient because for almost all purposes,
335 : : * quals attached to a semijoin can be treated the same as innerjoin quals.
336 : : */
337 : : #define IS_OUTER_JOIN(jointype) \
338 : : (((1 << (jointype)) & \
339 : : ((1 << JOIN_LEFT) | \
340 : : (1 << JOIN_FULL) | \
341 : : (1 << JOIN_RIGHT) | \
342 : : (1 << JOIN_ANTI) | \
343 : : (1 << JOIN_RIGHT_ANTI))) != 0)
344 : :
345 : : /*
346 : : * AggStrategy -
347 : : * overall execution strategies for Agg plan nodes
348 : : *
349 : : * This is needed in both pathnodes.h and plannodes.h, so put it here...
350 : : */
351 : : typedef enum AggStrategy
352 : : {
353 : : AGG_PLAIN, /* simple agg across all input rows */
354 : : AGG_SORTED, /* grouped agg, input must be sorted */
355 : : AGG_HASHED, /* grouped agg, use internal hashtable */
356 : : AGG_MIXED, /* grouped agg, hash and sort both used */
357 : : } AggStrategy;
358 : :
359 : : /*
360 : : * AggSplit -
361 : : * splitting (partial aggregation) modes for Agg plan nodes
362 : : *
363 : : * This is needed in both pathnodes.h and plannodes.h, so put it here...
364 : : */
365 : :
366 : : /* Primitive options supported by nodeAgg.c: */
367 : : #define AGGSPLITOP_COMBINE 0x01 /* substitute combinefn for transfn */
368 : : #define AGGSPLITOP_SKIPFINAL 0x02 /* skip finalfn, return state as-is */
369 : : #define AGGSPLITOP_SERIALIZE 0x04 /* apply serialfn to output */
370 : : #define AGGSPLITOP_DESERIALIZE 0x08 /* apply deserialfn to input */
371 : :
372 : : /* Supported operating modes (i.e., useful combinations of these options): */
373 : : typedef enum AggSplit
374 : : {
375 : : /* Basic, non-split aggregation: */
376 : : AGGSPLIT_SIMPLE = 0,
377 : : /* Initial phase of partial aggregation, with serialization: */
378 : : AGGSPLIT_INITIAL_SERIAL = AGGSPLITOP_SKIPFINAL | AGGSPLITOP_SERIALIZE,
379 : : /* Final phase of partial aggregation, with deserialization: */
380 : : AGGSPLIT_FINAL_DESERIAL = AGGSPLITOP_COMBINE | AGGSPLITOP_DESERIALIZE,
381 : : } AggSplit;
382 : :
383 : : /* Test whether an AggSplit value selects each primitive option: */
384 : : #define DO_AGGSPLIT_COMBINE(as) (((as) & AGGSPLITOP_COMBINE) != 0)
385 : : #define DO_AGGSPLIT_SKIPFINAL(as) (((as) & AGGSPLITOP_SKIPFINAL) != 0)
386 : : #define DO_AGGSPLIT_SERIALIZE(as) (((as) & AGGSPLITOP_SERIALIZE) != 0)
387 : : #define DO_AGGSPLIT_DESERIALIZE(as) (((as) & AGGSPLITOP_DESERIALIZE) != 0)
388 : :
389 : : /*
390 : : * SetOpCmd and SetOpStrategy -
391 : : * overall semantics and execution strategies for SetOp plan nodes
392 : : *
393 : : * This is needed in both pathnodes.h and plannodes.h, so put it here...
394 : : */
395 : : typedef enum SetOpCmd
396 : : {
397 : : SETOPCMD_INTERSECT,
398 : : SETOPCMD_INTERSECT_ALL,
399 : : SETOPCMD_EXCEPT,
400 : : SETOPCMD_EXCEPT_ALL,
401 : : } SetOpCmd;
402 : :
403 : : typedef enum SetOpStrategy
404 : : {
405 : : SETOP_SORTED, /* input must be sorted */
406 : : SETOP_HASHED, /* use internal hashtable */
407 : : } SetOpStrategy;
408 : :
409 : : /*
410 : : * OnConflictAction -
411 : : * "ON CONFLICT" clause type of query
412 : : *
413 : : * This is needed in both parsenodes.h and plannodes.h, so put it here...
414 : : */
415 : : typedef enum OnConflictAction
416 : : {
417 : : ONCONFLICT_NONE, /* No "ON CONFLICT" clause */
418 : : ONCONFLICT_NOTHING, /* ON CONFLICT ... DO NOTHING */
419 : : ONCONFLICT_UPDATE, /* ON CONFLICT ... DO UPDATE */
420 : : } OnConflictAction;
421 : :
422 : : /*
423 : : * LimitOption -
424 : : * LIMIT option of query
425 : : *
426 : : * This is needed in both parsenodes.h and plannodes.h, so put it here...
427 : : */
428 : : typedef enum LimitOption
429 : : {
430 : : LIMIT_OPTION_COUNT, /* FETCH FIRST... ONLY */
431 : : LIMIT_OPTION_WITH_TIES, /* FETCH FIRST... WITH TIES */
432 : : } LimitOption;
433 : :
434 : : #endif /* NODES_H */
|
