Adding upstream version 15.5.upstream/15.5

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 80 insertions, 0 deletions

diff --git a/src/backend/nodes/README b/src/backend/nodes/README
new file mode 100644
index 0000000..d066ac5
--- /dev/null
+++ b/src/backend/nodes/README
@@ -0,0 +1,80 @@
+src/backend/nodes/README
+
+Node Structures
+===============
+
+Andrew Yu (11/94)
+
+Introduction
+------------
+
+The current node structures are plain old C structures. "Inheritance" is
+achieved by convention. No additional functions will be generated. Functions
+that manipulate node structures reside in this directory.
+
+
+FILES IN THIS DIRECTORY (src/backend/nodes/)
+
+    General-purpose node manipulation functions:
+	copyfuncs.c	- copy a node tree
+	equalfuncs.c	- compare two node trees
+	outfuncs.c	- convert a node tree to text representation
+	readfuncs.c	- convert text representation back to a node tree
+	makefuncs.c	- creator functions for some common node types
+	nodeFuncs.c	- some other general-purpose manipulation functions
+
+    Specialized manipulation functions:
+	bitmapset.c	- Bitmapset support
+	list.c		- generic list support
+	params.c	- Param support
+	tidbitmap.c	- TIDBitmap support
+	value.c		- support for value nodes
+
+FILES IN src/include/nodes/
+
+    Node definitions:
+	nodes.h		- define node tags (NodeTag)
+	primnodes.h	- primitive nodes
+	parsenodes.h	- parse tree nodes
+	pathnodes.h	- path tree nodes and planner internal structures
+	plannodes.h	- plan tree nodes
+	execnodes.h	- executor nodes
+	memnodes.h	- memory nodes
+	pg_list.h	- generic list
+
+
+Steps to Add a Node
+-------------------
+
+Suppose you want to define a node Foo:
+
+1. Add a tag (T_Foo) to the enum NodeTag in nodes.h.  (If you insert the
+   tag in a way that moves the numbers associated with existing tags,
+   you'll need to recompile the whole tree after doing this.  It doesn't
+   force initdb though, because the numbers never go to disk.)
+2. Add the structure definition to the appropriate include/nodes/???.h file.
+   If you intend to inherit from, say a Plan node, put Plan as the first field
+   of your struct definition.
+3. If you intend to use copyObject, equal, nodeToString or stringToNode,
+   add an appropriate function to copyfuncs.c, equalfuncs.c, outfuncs.c
+   and readfuncs.c accordingly.  (Except for frequently used nodes, don't
+   bother writing a creator function in makefuncs.c)  The header comments
+   in those files give general rules for whether you need to add support.
+4. Add cases to the functions in nodeFuncs.c as needed.  There are many
+   other places you'll probably also need to teach about your new node
+   type.  Best bet is to grep for references to one or two similar existing
+   node types to find all the places to touch.
+
+
+Historical Note
+---------------
+
+Prior to the current simple C structure definitions, the Node structures
+used a pseudo-inheritance system which automatically generated creator and
+accessor functions. Since every node inherited from LispValue, the whole thing
+was a mess. Here's a little anecdote:
+
+    LispValue definition -- class used to support lisp structures
+    in C.  This is here because we did not want to totally rewrite
+    planner and executor code which depended on lisp structures when
+    we ported postgres V1 from lisp to C. -cim 4/23/90