LCOV - code coverage report
Current view: top level - src/include/nodes - nodes.h (source / functions) Hit Total Coverage
Test: PostgreSQL 18devel Lines: 4 4 100.0 %
Date: 2025-04-01 15:15:16 Functions: 1 1 100.0 %
Legend: Lines: hit not hit

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

Generated by: LCOV version 1.14