PostgreSQL Source Code  git master
nodes.h
Go to the documentation of this file.
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"
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 {
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  */
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 *
190 castNodeImpl(NodeTag type, void *ptr)
191 {
192  Assert(ptr == NULL || nodeTag(ptr) == type);
193  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 {
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 */
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  */
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 */
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: */
388  /* Initial phase of partial aggregation, with serialization: */
390  /* Final phase of partial aggregation, with deserialization: */
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 {
413 
414 typedef enum SetOpStrategy
415 {
416  SETOP_SORTED, /* input must be sorted */
417  SETOP_HASHED /* use internal hashtable */
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 */
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 */
445 
446 #endif /* NODES_H */
#define PGDLLIMPORT
Definition: c.h:1321
signed short int16
Definition: c.h:477
static struct @147 value
int b
Definition: isn.c:70
int a
Definition: isn.c:69
Assert(fmt[strlen(fmt) - 1] !='\n')
SetOpCmd
Definition: nodes.h:407
@ SETOPCMD_EXCEPT
Definition: nodes.h:410
@ SETOPCMD_EXCEPT_ALL
Definition: nodes.h:411
@ SETOPCMD_INTERSECT_ALL
Definition: nodes.h:409
@ SETOPCMD_INTERSECT
Definition: nodes.h:408
SetOpStrategy
Definition: nodes.h:415
@ SETOP_HASHED
Definition: nodes.h:417
@ SETOP_SORTED
Definition: nodes.h:416
double Cost
Definition: nodes.h:262
void outToken(struct StringInfoData *str, const char *s)
#define nodeTag(nodeptr)
Definition: nodes.h:133
struct Node Node
void outDatum(struct StringInfoData *str, uintptr_t value, int typlen, bool typbyval)
int * readIntCols(int numCols)
#define AGGSPLITOP_DESERIALIZE
Definition: nodes.h:381
#define AGGSPLITOP_SKIPFINAL
Definition: nodes.h:379
OnConflictAction
Definition: nodes.h:427
@ ONCONFLICT_NONE
Definition: nodes.h:428
@ ONCONFLICT_UPDATE
Definition: nodes.h:430
@ ONCONFLICT_NOTHING
Definition: nodes.h:429
#define AGGSPLITOP_SERIALIZE
Definition: nodes.h:380
PGDLLIMPORT Node * newNodeMacroHolder
Definition: nodes.c:31
struct Bitmapset * readBitmapset(void)
Definition: readfuncs.c:245
void outBitmapset(struct StringInfoData *str, const struct Bitmapset *bms)
double Cardinality
Definition: nodes.h:263
CmdType
Definition: nodes.h:274
@ CMD_MERGE
Definition: nodes.h:280
@ CMD_UTILITY
Definition: nodes.h:281
@ CMD_INSERT
Definition: nodes.h:278
@ CMD_DELETE
Definition: nodes.h:279
@ CMD_UNKNOWN
Definition: nodes.h:275
@ CMD_UPDATE
Definition: nodes.h:277
@ CMD_SELECT
Definition: nodes.h:276
@ CMD_NOTHING
Definition: nodes.h:283
bool equal(const void *a, const void *b)
Definition: equalfuncs.c:223
AggStrategy
Definition: nodes.h:363
@ AGG_SORTED
Definition: nodes.h:365
@ AGG_HASHED
Definition: nodes.h:366
@ AGG_MIXED
Definition: nodes.h:367
@ AGG_PLAIN
Definition: nodes.h:364
char * bmsToString(const struct Bitmapset *bms)
NodeTag
Definition: nodes.h:27
@ T_Invalid
Definition: nodes.h:28
double Selectivity
Definition: nodes.h:261
AggSplit
Definition: nodes.h:385
@ AGGSPLIT_FINAL_DESERIAL
Definition: nodes.h:391
@ AGGSPLIT_SIMPLE
Definition: nodes.h:387
@ AGGSPLIT_INITIAL_SERIAL
Definition: nodes.h:389
LimitOption
Definition: nodes.h:440
@ LIMIT_OPTION_COUNT
Definition: nodes.h:441
@ LIMIT_OPTION_WITH_TIES
Definition: nodes.h:442
@ LIMIT_OPTION_DEFAULT
Definition: nodes.h:443
void * stringToNode(const char *str)
Definition: read.c:90
bool * readBoolCols(int numCols)
#define AGGSPLITOP_COMBINE
Definition: nodes.h:378
Oid * readOidCols(int numCols)
void outNode(struct StringInfoData *str, const void *obj)
void * copyObjectImpl(const void *from)
Definition: copyfuncs.c:177
uintptr_t readDatum(bool typbyval)
Definition: readfuncs.c:732
int16 * readAttrNumberCols(int numCols)
JoinType
Definition: nodes.h:299
@ JOIN_SEMI
Definition: nodes.h:318
@ JOIN_FULL
Definition: nodes.h:306
@ JOIN_INNER
Definition: nodes.h:304
@ JOIN_RIGHT
Definition: nodes.h:307
@ JOIN_LEFT
Definition: nodes.h:305
@ JOIN_UNIQUE_OUTER
Definition: nodes.h:326
@ JOIN_RIGHT_ANTI
Definition: nodes.h:320
@ JOIN_UNIQUE_INNER
Definition: nodes.h:327
@ JOIN_ANTI
Definition: nodes.h:319
char * nodeToString(const void *obj)
Definition: outfuncs.c:877
unsigned int Oid
Definition: postgres_ext.h:31
Definition: nodes.h:129
NodeTag type
Definition: nodes.h:130