src/include/nodes/extensible.h

   1 /*-------------------------------------------------------------------------
   2  *
   3  * extensible.h
   4  *        Definitions for extensible nodes and custom scans
   5  *
   6  *
   7  * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
   8  * Portions Copyright (c) 1994, Regents of the University of California
   9  *
  10  * src/include/nodes/extensible.h
  11  *
  12  *-------------------------------------------------------------------------
  13  */
  14 #ifndef EXTENSIBLE_H
  15 #define EXTENSIBLE_H
  16
  17 #include "access/parallel.h"
  18 #include "commands/explain.h"
  19 #include "nodes/execnodes.h"
  20 #include "nodes/pathnodes.h"
  21 #include "nodes/plannodes.h"
  22
  23 /* maximum length of an extensible node identifier */
  24 #define EXTNODENAME_MAX_LEN                                     64
  25
  26 /*
  27  * An extensible node is a new type of node defined by an extension.  The
  28  * type is always T_ExtensibleNode, while the extnodename identifies the
  29  * specific type of node.  extnodename can be looked up to find the
  30  * ExtensibleNodeMethods for this node type.
  31  */
  32 typedef struct ExtensibleNode
  33 {
  34         pg_node_attr(custom_copy_equal, custom_read_write)
  35
  36         NodeTag         type;
  37         const char *extnodename;        /* identifier of ExtensibleNodeMethods */
  38 } ExtensibleNode;
  39
  40 /*
  41  * node_size is the size of an extensible node of this type in bytes.
  42  *
  43  * nodeCopy is a function which performs a deep copy from oldnode to newnode.
  44  * It does not need to copy type or extnodename, which are copied by the
  45  * core system.
  46  *
  47  * nodeEqual is a function which performs a deep equality comparison between
  48  * a and b and returns true or false accordingly.  It does not need to compare
  49  * type or extnodename, which are compared by the core system.
  50  *
  51  * nodeOut is a serialization function for the node type.  It should use the
  52  * output conventions typical for outfuncs.c.  It does not need to output
  53  * type or extnodename; the core system handles those.
  54  *
  55  * nodeRead is a deserialization function for the node type.  It does not need
  56  * to read type or extnodename; the core system handles those.  It should fetch
  57  * the next token using pg_strtok() from the current input stream, and then
  58  * reconstruct the private fields according to the manner in readfuncs.c.
  59  *
  60  * All callbacks are mandatory.
  61  */
  62 typedef struct ExtensibleNodeMethods
  63 {
  64         const char *extnodename;
  65         Size            node_size;
  66         void            (*nodeCopy) (struct ExtensibleNode *newnode,
  67                                                          const struct ExtensibleNode *oldnode);
  68         bool            (*nodeEqual) (const struct ExtensibleNode *a,
  69                                                           const struct ExtensibleNode *b);
  70         void            (*nodeOut) (struct StringInfoData *str,
  71                                                         const struct ExtensibleNode *node);
  72         void            (*nodeRead) (struct ExtensibleNode *node);
  73 } ExtensibleNodeMethods;
  74
  75 extern void RegisterExtensibleNodeMethods(const ExtensibleNodeMethods *methods);
  76 extern const ExtensibleNodeMethods *GetExtensibleNodeMethods(const char *extnodename,
  77                                                                                                                          bool missing_ok);
  78
  79 /*
  80  * Flags for custom paths, indicating what capabilities the resulting scan
  81  * will have.  The flags fields of CustomPath and CustomScan nodes are
  82  * bitmasks of these flags.
  83  */
  84 #define CUSTOMPATH_SUPPORT_BACKWARD_SCAN        0x0001
  85 #define CUSTOMPATH_SUPPORT_MARK_RESTORE         0x0002
  86 #define CUSTOMPATH_SUPPORT_PROJECTION           0x0004
  87
  88 /*
  89  * Custom path methods.  Mostly, we just need to know how to convert a
  90  * CustomPath to a plan.
  91  */
  92 typedef struct CustomPathMethods
  93 {
  94         const char *CustomName;
  95
  96         /* Convert Path to a Plan */
  97         struct Plan *(*PlanCustomPath) (PlannerInfo *root,
  98                                                                         RelOptInfo *rel,
  99                                                                         struct CustomPath *best_path,
 100                                                                         List *tlist,
 101                                                                         List *clauses,
 102                                                                         List *custom_plans);
 103         struct List *(*ReparameterizeCustomPathByChild) (PlannerInfo *root,
 104                                                                                                          List *custom_private,
 105                                                                                                          RelOptInfo *child_rel);
 106 }                       CustomPathMethods;
 107
 108 /*
 109  * Custom scan.  Here again, there's not much to do: we need to be able to
 110  * generate a ScanState corresponding to the scan.
 111  */
 112 typedef struct CustomScanMethods
 113 {
 114         const char *CustomName;
 115
 116         /* Create execution state (CustomScanState) from a CustomScan plan node */
 117         Node       *(*CreateCustomScanState) (CustomScan *cscan);
 118 } CustomScanMethods;
 119
 120 /*
 121  * Execution-time methods for a CustomScanState.  This is more complex than
 122  * what we need for a custom path or scan.
 123  */
 124 typedef struct CustomExecMethods
 125 {
 126         const char *CustomName;
 127
 128         /* Required executor methods */
 129         void            (*BeginCustomScan) (CustomScanState *node,
 130                                                                         EState *estate,
 131                                                                         int eflags);
 132         TupleTableSlot *(*ExecCustomScan) (CustomScanState *node);
 133         void            (*EndCustomScan) (CustomScanState *node);
 134         void            (*ReScanCustomScan) (CustomScanState *node);
 135
 136         /* Optional methods: needed if mark/restore is supported */
 137         void            (*MarkPosCustomScan) (CustomScanState *node);
 138         void            (*RestrPosCustomScan) (CustomScanState *node);
 139
 140         /* Optional methods: needed if parallel execution is supported */
 141         Size            (*EstimateDSMCustomScan) (CustomScanState *node,
 142                                                                                   ParallelContext *pcxt);
 143         void            (*InitializeDSMCustomScan) (CustomScanState *node,
 144                                                                                         ParallelContext *pcxt,
 145                                                                                         void *coordinate);
 146         void            (*ReInitializeDSMCustomScan) (CustomScanState *node,
 147                                                                                           ParallelContext *pcxt,
 148                                                                                           void *coordinate);
 149         void            (*InitializeWorkerCustomScan) (CustomScanState *node,
 150                                                                                            shm_toc *toc,
 151                                                                                            void *coordinate);
 152         void            (*ShutdownCustomScan) (CustomScanState *node);
 153
 154         /* Optional: print additional information in EXPLAIN */
 155         void            (*ExplainCustomScan) (CustomScanState *node,
 156                                                                           List *ancestors,
 157                                                                           ExplainState *es);
 158 } CustomExecMethods;
 159
 160 extern void RegisterCustomScanMethods(const CustomScanMethods *methods);
 161 extern const CustomScanMethods *GetCustomScanMethods(const char *CustomName,
 162                                                                                                          bool missing_ok);
 163
 164 #endif                                                  /* EXTENSIBLE_H */