From 3cd0ac987819280eb8dd3e0997f0294b8bc6355a Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Sat, 9 Jul 2022 15:10:15 -0400 Subject: [PATCH] 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/3843645.1657385930@sss.pgh.pa.us --- src/backend/nodes/README | 26 +++++++++++++++++++++++++- src/backend/nodes/outfuncs.c | 13 ------------- src/backend/nodes/readfuncs.c | 6 +----- src/include/nodes/execnodes.h | 21 +++++++++++++++------ 4 files changed, 41 insertions(+), 25 deletions(-) diff --git a/src/backend/nodes/README b/src/backend/nodes/README index b3dc9afaf77..64937fe254b 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 9e70bbb4d69..4d776e7b51b 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 67b0f798c15..1421686938f 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 967604b8a50..01b1727fc09 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. * ---------------- */ -- 2.30.2