Introduction
------------
+Postgres uses "node" types to organize parse trees, plan trees, and
+executor state trees. All objects that can appear in such trees must
+be declared as node types. In addition, a few object types that aren't
+part of parse/plan/execute node trees receive NodeTags anyway for
+identification purposes, usually because they are involved in APIs
+where we want to pass multiple object types through the same pointer.
+
The node structures are plain old C structures with the first field
being of type NodeTag. "Inheritance" is achieved by convention:
the first field can alternatively be of another node type.
+Node types typically have support for being copied by copyObject(),
+compared by equal(), serialized by outNode(), and deserialized by
+nodeRead(). For some classes of Nodes, not all of these support
+functions are required; for example, executor state nodes don't
+presently need any of them. So far as the system is concerned,
+output and read functions are only needed for node types that can
+appear in parse trees stored in the catalogs, and for plan tree
+nodes because those are serialized to be passed to parallel workers.
+However, we provide output functions for some other node types as well,
+because they are very handy for debugging. Currently, such coverage
+exists for raw parsetrees and most planner data structures. However,
+output coverage of raw parsetrees is incomplete: in particular, utility
+statements are almost entirely unsupported.
+
+Relevant Files
+--------------
+
Utility functions for manipulating node structures reside in this
directory. Some support functions are automatically generated by the
gen_node_support.pl script, other functions are maintained manually.
FILES IN src/include/nodes/
- Node definitions:
+ Node definitions primarily appear in:
nodes.h - define node tags (NodeTag) (*)
primnodes.h - primitive nodes
parsenodes.h - parse tree nodes
* IDENTIFICATION
* src/backend/nodes/outfuncs.c
*
- * NOTES
- * Every node type that can appear in stored rules' parsetrees *must*
- * have an output function defined here (as well as an input function
- * in readfuncs.c). In addition, plan nodes should have input and
- * output functions so that they can be sent to parallel workers.
- *
- * For use in debugging, we also provide output functions for nodes
- * that appear in raw parsetrees and planner Paths. These node types
- * need not have input functions. Output support for raw parsetrees
- * is somewhat incomplete, too; in particular, utility statements are
- * almost entirely unsupported. We try to support everything that can
- * appear in a raw SELECT, though.
- *
*-------------------------------------------------------------------------
*/
#include "postgres.h"
* src/backend/nodes/readfuncs.c
*
* NOTES
- * Path nodes do not have any readfuncs support, because we never
- * have occasion to read them in. (There was once code here that
- * claimed to read them, but it was broken as well as unused.) We
- * never read executor state trees, either.
- *
* Parse location fields are written out by outfuncs.c, but only for
* debugging use. When reading a location field, we normally discard
* the stored value and set the location field to -1 (ie, "unknown").
* This is because nodes coming from a stored rule should not be thought
* to have a known location in the current query's text.
+ *
* However, if restore_location_fields is true, we do restore location
* fields from the string. This is currently intended only for use by the
* WRITE_READ_PARSE_PLAN_TREES test code, which doesn't want to cause
* execnodes.h
* definitions for executor state nodes
*
- * ExprState represents the evaluation state for a whole expression tree.
- * Most Expr-based plan nodes do not have a corresponding expression state
- * node, they're fully handled within execExpr* - but sometimes the state
- * needs to be shared with other parts of the executor, as for example
- * with SubPlanState, which nodeSubplan.c has to modify.
+ * Most plan node types declared in plannodes.h have a corresponding
+ * execution-state node type declared here. An exception is that
+ * expression nodes (subtypes of Expr) are usually represented by steps
+ * of an ExprState, and fully handled within execExpr* - but sometimes
+ * their state needs to be shared with other parts of the executor, as
+ * for example with SubPlanState, which nodeSubplan.c has to modify.
+ *
+ * Node types declared in this file do not have any copy/equal/out/read
+ * support. (That is currently hard-wired in gen_node_support.pl, rather
+ * than being explicitly represented by pg_node_attr decorations here.)
+ * There is no need for copy, equal, or read support for executor trees.
+ * Output support could be useful for debugging; but there are a lot of
+ * specialized fields that would require custom code, so for now it's
+ * not provided.
*
*
* Portions Copyright (c) 1996-2022, PostgreSQL Global Development Group
/* ----------------
* ExprState node
*
- * ExprState is the top-level node for expression evaluation.
+ * ExprState represents the evaluation state for a whole expression tree.
* It contains instructions (in ->steps) to evaluate the expression.
* ----------------
*/
projects / postgresql.git / commitdiff