PostgreSQL Source Code  git master
dest.h
Go to the documentation of this file.
1 /*-------------------------------------------------------------------------
2  *
3  * dest.h
4  * support for communication destinations
5  *
6  * Whenever the backend executes a query that returns tuples, the results
7  * have to go someplace. For example:
8  *
9  * - stdout is the destination only when we are running a
10  * standalone backend (no postmaster) and are returning results
11  * back to an interactive user.
12  *
13  * - a remote process is the destination when we are
14  * running a backend with a frontend and the frontend executes
15  * PQexec() or PQfn(). In this case, the results are sent
16  * to the frontend via the functions in backend/libpq.
17  *
18  * - DestNone is the destination when the system executes
19  * a query internally. The results are discarded.
20  *
21  * dest.c defines three functions that implement destination management:
22  *
23  * BeginCommand: initialize the destination at start of command.
24  * CreateDestReceiver: return a pointer to a struct of destination-specific
25  * receiver functions.
26  * EndCommand: clean up the destination at end of command.
27  *
28  * BeginCommand/EndCommand are executed once per received SQL query.
29  *
30  * CreateDestReceiver returns a receiver object appropriate to the specified
31  * destination. The executor, as well as utility statements that can return
32  * tuples, are passed the resulting DestReceiver* pointer. Each executor run
33  * or utility execution calls the receiver's rStartup method, then the
34  * receiveSlot method (zero or more times), then the rShutdown method.
35  * The same receiver object may be re-used multiple times; eventually it is
36  * destroyed by calling its rDestroy method.
37  *
38  * In some cases, receiver objects require additional parameters that must
39  * be passed to them after calling CreateDestReceiver. Since the set of
40  * parameters varies for different receiver types, this is not handled by
41  * this module, but by direct calls from the calling code to receiver type
42  * specific functions.
43  *
44  * The DestReceiver object returned by CreateDestReceiver may be a statically
45  * allocated object (for destination types that require no local state),
46  * in which case rDestroy is a no-op. Alternatively it can be a palloc'd
47  * object that has DestReceiver as its first field and contains additional
48  * fields (see printtup.c for an example). These additional fields are then
49  * accessible to the DestReceiver functions by casting the DestReceiver*
50  * pointer passed to them. The palloc'd object is pfree'd by the rDestroy
51  * method. Note that the caller of CreateDestReceiver should take care to
52  * do so in a memory context that is long-lived enough for the receiver
53  * object not to disappear while still needed.
54  *
55  * Special provision: None_Receiver is a permanently available receiver
56  * object for the DestNone destination. This avoids useless creation/destroy
57  * calls in portal and cursor manipulations.
58  *
59  *
60  * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
61  * Portions Copyright (c) 1994, Regents of the University of California
62  *
63  * src/include/tcop/dest.h
64  *
65  *-------------------------------------------------------------------------
66  */
67 #ifndef DEST_H
68 #define DEST_H
69 
70 #include "executor/tuptable.h"
71 #include "tcop/cmdtag.h"
72 
73 
74 
75 
76 /* ----------------
77  * CommandDest is a simplistic means of identifying the desired
78  * destination. Someday this will probably need to be improved.
79  *
80  * Note: only the values DestNone, DestDebug, DestRemote are legal for the
81  * global variable whereToSendOutput. The other values may be used
82  * as the destination for individual commands.
83  * ----------------
84  */
85 typedef enum
86 {
87  DestNone, /* results are discarded */
88  DestDebug, /* results go to debugging output */
89  DestRemote, /* results sent to frontend process */
90  DestRemoteExecute, /* sent to frontend, in Execute command */
91  DestRemoteSimple, /* sent to frontend, w/no catalog access */
92  DestSPI, /* results sent to SPI manager */
93  DestTuplestore, /* results sent to Tuplestore */
94  DestIntoRel, /* results sent to relation (SELECT INTO) */
95  DestCopyOut, /* results sent to COPY TO code */
96  DestSQLFunction, /* results sent to SQL-language func mgr */
97  DestTransientRel, /* results sent to transient relation */
98  DestTupleQueue, /* results sent to tuple queue */
99 } CommandDest;
100 
101 /* ----------------
102  * DestReceiver is a base type for destination-specific local state.
103  * In the simplest cases, there is no state info, just the function
104  * pointers that the executor must call.
105  *
106  * Note: the receiveSlot routine must be passed a slot containing a TupleDesc
107  * identical to the one given to the rStartup routine. It returns bool where
108  * a "true" value means "continue processing" and a "false" value means
109  * "stop early, just as if we'd reached the end of the scan".
110  * ----------------
111  */
112 typedef struct _DestReceiver DestReceiver;
113 
115 {
116  /* Called for each tuple to be output: */
118  DestReceiver *self);
119  /* Per-executor-run initialization and shutdown: */
120  void (*rStartup) (DestReceiver *self,
121  int operation,
122  TupleDesc typeinfo);
123  void (*rShutdown) (DestReceiver *self);
124  /* Destroy the receiver object itself (if dynamically allocated) */
125  void (*rDestroy) (DestReceiver *self);
126  /* CommandDest code for this receiver */
128  /* Private fields might appear beyond this point... */
129 };
130 
131 extern PGDLLIMPORT DestReceiver *None_Receiver; /* permanent receiver for
132  * DestNone */
133 
134 /* The primary destination management functions */
135 
136 extern void BeginCommand(CommandTag commandTag, CommandDest dest);
138 extern void EndCommand(const QueryCompletion *qc, CommandDest dest,
139  bool force_undecorated_output);
140 extern void EndReplicationCommand(const char *commandTag);
141 
142 /* Additional functions that go with destination management, more or less. */
143 
144 extern void NullCommand(CommandDest dest);
145 extern void ReadyForQuery(CommandDest dest);
146 
147 #endif /* DEST_H */
#define PGDLLIMPORT
Definition: c.h:1303
unsigned char bool
Definition: c.h:443
CommandTag
Definition: cmdtag.h:23
void EndCommand(const QueryCompletion *qc, CommandDest dest, bool force_undecorated_output)
Definition: dest.c:165
CommandDest
Definition: dest.h:86
@ DestSQLFunction
Definition: dest.h:96
@ DestTupleQueue
Definition: dest.h:98
@ DestTuplestore
Definition: dest.h:93
@ DestRemote
Definition: dest.h:89
@ DestDebug
Definition: dest.h:88
@ DestRemoteSimple
Definition: dest.h:91
@ DestCopyOut
Definition: dest.h:95
@ DestTransientRel
Definition: dest.h:97
@ DestSPI
Definition: dest.h:92
@ DestIntoRel
Definition: dest.h:94
@ DestRemoteExecute
Definition: dest.h:90
@ DestNone
Definition: dest.h:87
void BeginCommand(CommandTag commandTag, CommandDest dest)
Definition: dest.c:102
void ReadyForQuery(CommandDest dest)
Definition: dest.c:250
void EndReplicationCommand(const char *commandTag)
Definition: dest.c:200
DestReceiver * CreateDestReceiver(CommandDest dest)
Definition: dest.c:112
void NullCommand(CommandDest dest)
Definition: dest.c:213
PGDLLIMPORT DestReceiver * None_Receiver
Definition: dest.c:95
void(* rStartup)(DestReceiver *self, int operation, TupleDesc typeinfo)
Definition: dest.h:120
void(* rShutdown)(DestReceiver *self)
Definition: dest.h:123
bool(* receiveSlot)(TupleTableSlot *slot, DestReceiver *self)
Definition: dest.h:117
void(* rDestroy)(DestReceiver *self)
Definition: dest.h:125
CommandDest mydest
Definition: dest.h:127