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