summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorTom Lane2022-07-09 19:10:15 +0000
committerTom Lane2022-07-09 19:10:15 +0000
commit3cd0ac987819280eb8dd3e0997f0294b8bc6355a (patch)
treeadcb32ec90bca7d80e16bbd4e2cbf2d4242d4a85
parent8c73c11a0d39049de2c1f400d8765a0eb21f5228 (diff)
Doc: rearrange high-level commentary about node support coverage.
copyfuncs.c and friends no longer seem like great places to put high-level remarks about what's covered and what isn't. Move that material to backend/nodes/README and other more-prominent places. Add back (versions of) some remarks that disappeared in 2be87f092. Discussion: https://postgr.es/m/[email protected]
-rw-r--r--src/backend/nodes/README26
-rw-r--r--src/backend/nodes/outfuncs.c13
-rw-r--r--src/backend/nodes/readfuncs.c6
-rw-r--r--src/include/nodes/execnodes.h21
4 files changed, 41 insertions, 25 deletions
diff --git a/src/backend/nodes/README b/src/backend/nodes/README
index b3dc9afaf7..64937fe254 100644
--- a/src/backend/nodes/README
+++ b/src/backend/nodes/README
@@ -6,10 +6,34 @@ Node Structures
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.
@@ -40,7 +64,7 @@ FILES IN THIS DIRECTORY (src/backend/nodes/)
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
diff --git a/src/backend/nodes/outfuncs.c b/src/backend/nodes/outfuncs.c
index 9e70bbb4d6..4d776e7b51 100644
--- a/src/backend/nodes/outfuncs.c
+++ b/src/backend/nodes/outfuncs.c
@@ -10,19 +10,6 @@
* 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"
diff --git a/src/backend/nodes/readfuncs.c b/src/backend/nodes/readfuncs.c
index 67b0f798c1..1421686938 100644
--- a/src/backend/nodes/readfuncs.c
+++ b/src/backend/nodes/readfuncs.c
@@ -11,16 +11,12 @@
* 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
diff --git a/src/include/nodes/execnodes.h b/src/include/nodes/execnodes.h
index 967604b8a5..01b1727fc0 100644
--- a/src/include/nodes/execnodes.h
+++ b/src/include/nodes/execnodes.h
@@ -3,11 +3,20 @@
* 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
@@ -53,7 +62,7 @@ struct LogicalTapeSet;
/* ----------------
* 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.
* ----------------
*/