PostgreSQL Source Code  git master
extensible.h
Go to the documentation of this file.
1 /*-------------------------------------------------------------------------
2  *
3  * extensible.h
4  * Definitions for extensible nodes and custom scans
5  *
6  *
7  * Portions Copyright (c) 1996-2023, 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 */
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;
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);
74 
75 extern void RegisterExtensibleNodeMethods(const ExtensibleNodeMethods *methods);
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);
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);
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 */
130  EState *estate,
131  int eflags);
132  TupleTableSlot *(*ExecCustomScan) (CustomScanState *node);
135 
136  /* Optional methods: needed if mark/restore is supported */
139 
140  /* Optional methods: needed if parallel execution is supported */
142  ParallelContext *pcxt);
144  ParallelContext *pcxt,
145  void *coordinate);
147  ParallelContext *pcxt,
148  void *coordinate);
150  shm_toc *toc,
151  void *coordinate);
153 
154  /* Optional: print additional information in EXPLAIN */
156  List *ancestors,
157  ExplainState *es);
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 */
unsigned char bool
Definition: c.h:440
size_t Size
Definition: c.h:589
struct CustomExecMethods CustomExecMethods
struct CustomScanMethods CustomScanMethods
struct CustomPathMethods CustomPathMethods
void RegisterExtensibleNodeMethods(const ExtensibleNodeMethods *methods)
Definition: extensible.c:76
struct ExtensibleNodeMethods ExtensibleNodeMethods
void RegisterCustomScanMethods(const CustomScanMethods *methods)
Definition: extensible.c:88
const CustomScanMethods * GetCustomScanMethods(const char *CustomName, bool missing_ok)
Definition: extensible.c:137
const ExtensibleNodeMethods * GetExtensibleNodeMethods(const char *extnodename, bool missing_ok)
Definition: extensible.c:125
struct ExtensibleNode ExtensibleNode
int b
Definition: isn.c:70
int a
Definition: isn.c:69
NodeTag
Definition: nodes.h:27
void(* BeginCustomScan)(CustomScanState *node, EState *estate, int eflags)
Definition: extensible.h:129
void(* EndCustomScan)(CustomScanState *node)
Definition: extensible.h:133
void(* ShutdownCustomScan)(CustomScanState *node)
Definition: extensible.h:152
const char * CustomName
Definition: extensible.h:126
void(* ReInitializeDSMCustomScan)(CustomScanState *node, ParallelContext *pcxt, void *coordinate)
Definition: extensible.h:146
void(* InitializeDSMCustomScan)(CustomScanState *node, ParallelContext *pcxt, void *coordinate)
Definition: extensible.h:143
void(* RestrPosCustomScan)(CustomScanState *node)
Definition: extensible.h:138
Size(* EstimateDSMCustomScan)(CustomScanState *node, ParallelContext *pcxt)
Definition: extensible.h:141
void(* MarkPosCustomScan)(CustomScanState *node)
Definition: extensible.h:137
void(* InitializeWorkerCustomScan)(CustomScanState *node, shm_toc *toc, void *coordinate)
Definition: extensible.h:149
void(* ExplainCustomScan)(CustomScanState *node, List *ancestors, ExplainState *es)
Definition: extensible.h:155
void(* ReScanCustomScan)(CustomScanState *node)
Definition: extensible.h:134
const char * CustomName
Definition: extensible.h:94
const char * CustomName
Definition: extensible.h:114
void(* nodeRead)(struct ExtensibleNode *node)
Definition: extensible.h:72
void(* nodeCopy)(struct ExtensibleNode *newnode, const struct ExtensibleNode *oldnode)
Definition: extensible.h:66
bool(* nodeEqual)(const struct ExtensibleNode *a, const struct ExtensibleNode *b)
Definition: extensible.h:68
void(* nodeOut)(struct StringInfoData *str, const struct ExtensibleNode *node)
Definition: extensible.h:70
const char * extnodename
Definition: extensible.h:64
pg_node_attr(custom_copy_equal, custom_read_write) NodeTag type
const char * extnodename
Definition: extensible.h:37
Definition: pg_list.h:54
Definition: nodes.h:118