Debian Codegraph @

src/backend/nodes/README

raw
1 src/backend/nodes/README
2
3 Node Structures
4 ===============
5
6 Introduction
7 ------------
8
9 Postgres uses "node" types to organize parse trees, plan trees, and
10 executor state trees. All objects that can appear in such trees must
11 be declared as node types. In addition, a few object types that aren't
12 part of parse/plan/execute node trees receive NodeTags anyway for
13 identification purposes, usually because they are involved in APIs
14 where we want to pass multiple object types through the same pointer.
15
16 The node structures are plain old C structures with the first field
17 being of type NodeTag. "Inheritance" is achieved by convention:
18 the first field can alternatively be of another node type.
19
20 Node types typically have support for being copied by copyObject(),
21 compared by equal(), serialized by outNode(), and deserialized by
22 nodeRead(). For some classes of Nodes, not all of these support
23 functions are required; for example, executor state nodes don't
24 presently need any of them. So far as the system is concerned,
25 output and read functions are only needed for node types that can
26 appear in parse trees stored in the catalogs, and for plan tree
27 nodes because those are serialized to be passed to parallel workers.
28 However, we provide output functions for some other node types as well,
29 because they are very handy for debugging. Currently, such coverage
30 exists for raw parsetrees and most planner data structures. However,
31 output coverage of raw parsetrees is incomplete: in particular, utility
32 statements are almost entirely unsupported.
33
34 Relevant Files
35 --------------
36
37 Utility functions for manipulating node structures reside in this
38 directory. Some support functions are automatically generated by the
39 gen_node_support.pl script, other functions are maintained manually.
40 To control the automatic generation of support functions, node types
41 and node fields can be annotated with pg_node_attr() specifications;
42 see further documentation in src/include/nodes/nodes.h.
43
44
45 FILES IN THIS DIRECTORY (src/backend/nodes/)
46
47 General-purpose node manipulation functions:
48 copyfuncs.c - copy a node tree (*)
49 equalfuncs.c - compare two node trees (*)
50 outfuncs.c - convert a node tree to text representation (*)
51 readfuncs.c - convert text representation back to a node tree (*)
52 makefuncs.c - creator functions for some common node types
53 nodeFuncs.c - some other general-purpose manipulation functions
54 queryjumblefuncs.c - compute a node tree for query jumbling (*)
55
56 (*) - Most functions in these files are generated by
57 gen_node_support.pl and #include'd there.
58
59 Specialized manipulation functions:
60 bitmapset.c - Bitmapset support
61 list.c - generic list support
62 multibitmapset.c - List-of-Bitmapset support
63 params.c - Param support
64 tidbitmap.c - TIDBitmap support
65 value.c - support for value nodes
66
67 FILES IN src/include/nodes/
68
69 Node definitions primarily appear in:
70 nodes.h - define node tags (NodeTag) (*)
71 primnodes.h - primitive nodes
72 parsenodes.h - parse tree nodes
73 pathnodes.h - path tree nodes and planner internal structures
74 plannodes.h - plan tree nodes
75 execnodes.h - executor nodes
76 memnodes.h - memory nodes
77 pg_list.h - generic list
78
79 (*) - Also #include's files generated by gen_node_support.pl.
80
81
82 Steps to Add a Node
83 -------------------
84
85 Suppose you want to define a node Foo:
86
87 1. Add the structure definition to the appropriate include/nodes/???.h file.
88 If you intend to inherit from, say a Plan node, put Plan as the first field
89 of your struct definition. (The T_Foo tag is created automatically.)
90 2. Check that the generated support functions in copyfuncs.funcs.c,
91 equalfuncs.funcs.c, outfuncs.funcs.c, queryjumblefuncs.funcs.c and
92 readfuncs.funcs.c look correct. Add attributes as necessary to control the
93 outcome. (For some classes of node types, you don't need all the support
94 functions. Use node attributes similar to those of related node types.)
95 3. Add cases to the functions in nodeFuncs.c as needed. There are many
96 other places you'll probably also need to teach about your new node
97 type. Best bet is to grep for references to one or two similar existing
98 node types to find all the places to touch.
99 (Except for frequently-created nodes, don't bother writing a creator
100 function in makefuncs.c.)
101 4. Consider testing your new code with debug_copy_parse_plan_trees,
102 debug_write_read_parse_plan_trees, and
103 debug_raw_expression_coverage_test to ensure support has been added
104 everywhere that it's necessary (e.g., run the tests with
105 PG_TEST_INITDB_EXTRA_OPTS='-c debug_...=on').
106
107 Adding a new node type moves the numbers associated with existing
108 tags, so you'll need to recompile the whole tree after doing this.
109 (--enable-depend usually helps.) It doesn't force initdb though,
110 because the numbers never go to disk. But altering or removing a node
111 type should usually be accompanied by an initdb-forcing catalog
112 version change, since the interpretation of serialized node trees
113 stored in system catalogs is affected by that. (If the node type
114 never appears in stored parse trees, as for example Plan nodes do not,
115 then a catversion change is not needed to change it.)