| 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.) |