granicus.if.org Git - postgresql/blob - src/backend/nodes/README

   1 src/backend/nodes/README
   2
   3 Node Structures
   4 ===============
   5
   6 Andrew Yu (11/94)
   7
   8 Introduction
   9 ------------
  10
  11 The current node structures are plain old C structures. "Inheritance" is
  12 achieved by convention. No additional functions will be generated. Functions
  13 that manipulate node structures reside in this directory.
  14
  15
  16 FILES IN THIS DIRECTORY (src/backend/nodes/)
  17
  18     General-purpose node manipulation functions:
  19         copyfuncs.c     - copy a node tree
  20         equalfuncs.c    - compare two node trees
  21         outfuncs.c      - convert a node tree to text representation
  22         readfuncs.c     - convert text representation back to a node tree
  23         makefuncs.c     - creator functions for some common node types
  24         nodeFuncs.c     - some other general-purpose manipulation functions
  25
  26     Specialized manipulation functions:
  27         bitmapset.c     - Bitmapset support
  28         list.c          - generic list support
  29         params.c        - Param support
  30         tidbitmap.c     - TIDBitmap support
  31         value.c         - support for Value nodes
  32
  33 FILES IN src/include/nodes/
  34
  35     Node definitions:
  36         nodes.h         - define node tags (NodeTag)
  37         primnodes.h     - primitive nodes
  38         parsenodes.h    - parse tree nodes
  39         plannodes.h     - plan tree nodes
  40         relation.h      - planner internal nodes
  41         execnodes.h     - executor nodes
  42         memnodes.h      - memory nodes
  43         pg_list.h       - generic list
  44
  45
  46 Steps to Add a Node
  47 -------------------
  48
  49 Suppose you wanna define a node Foo:
  50
  51 1. Add a tag (T_Foo) to the enum NodeTag in nodes.h.  (If you insert the
  52    tag in a way that moves the numbers associated with existing tags,
  53    you'll need to recompile the whole tree after doing this.  It doesn't
  54    force initdb though, because the numbers never go to disk.)
  55 2. Add the structure definition to the appropriate include/nodes/???.h file.
  56    If you intend to inherit from, say a Plan node, put Plan as the first field
  57    of your struct definition.
  58 3. If you intend to use copyObject, equal, nodeToString or stringToNode,
  59    add an appropriate function to copyfuncs.c, equalfuncs.c, outfuncs.c
  60    and readfuncs.c accordingly.  (Except for frequently used nodes, don't
  61    bother writing a creator function in makefuncs.c)  The header comments
  62    in those files give general rules for whether you need to add support.
  63 4. Add cases to the functions in nodeFuncs.c as needed.  There are many
  64    other places you'll probably also need to teach about your new node
  65    type.  Best bet is to grep for references to one or two similar existing
  66    node types to find all the places to touch.
  67
  68
  69 Historical Note
  70 ---------------
  71
  72 Prior to the current simple C structure definitions, the Node structures
  73 used a pseudo-inheritance system which automatically generated creator and
  74 accessor functions. Since every node inherited from LispValue, the whole thing
  75 was a mess. Here's a little anecdote:
  76
  77     LispValue definition -- class used to support lisp structures
  78     in C.  This is here because we did not want to totally rewrite
  79     planner and executor code which depended on lisp structures when
  80     we ported postgres V1 from lisp to C. -cim 4/23/90