PostgreSQL Source Code git master
All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
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 */
85typedef 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 DestExplainSerialize, /* results are serialized and discarded */
101
102/* ----------------
103 * DestReceiver is a base type for destination-specific local state.
104 * In the simplest cases, there is no state info, just the function
105 * pointers that the executor must call.
106 *
107 * Note: the receiveSlot routine must be passed a slot containing a TupleDesc
108 * identical to the one given to the rStartup routine. It returns bool where
109 * a "true" value means "continue processing" and a "false" value means
110 * "stop early, just as if we'd reached the end of the scan".
111 * ----------------
112 */
114
116{
117 /* Called for each tuple to be output: */
119 DestReceiver *self);
120 /* Per-executor-run initialization and shutdown: */
121 void (*rStartup) (DestReceiver *self,
122 int operation,
123 TupleDesc typeinfo);
124 void (*rShutdown) (DestReceiver *self);
125 /* Destroy the receiver object itself (if dynamically allocated) */
126 void (*rDestroy) (DestReceiver *self);
127 /* CommandDest code for this receiver */
129 /* Private fields might appear beyond this point... */
130};
131
132extern PGDLLIMPORT DestReceiver *None_Receiver; /* permanent receiver for
133 * DestNone */
134
135/* The primary destination management functions */
136
137extern void BeginCommand(CommandTag commandTag, CommandDest dest);
139extern void EndCommand(const QueryCompletion *qc, CommandDest dest,
140 bool force_undecorated_output);
141extern void EndReplicationCommand(const char *commandTag);
142
143/* Additional functions that go with destination management, more or less. */
144
145extern void NullCommand(CommandDest dest);
146extern void ReadyForQuery(CommandDest dest);
147
148#endif /* DEST_H */
#define PGDLLIMPORT
Definition: c.h:1274
CommandTag
Definition: cmdtag.h:23
void EndCommand(const QueryCompletion *qc, CommandDest dest, bool force_undecorated_output)
Definition: dest.c:169
DestReceiver * CreateDestReceiver(CommandDest dest)
Definition: dest.c:113
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
@ DestExplainSerialize
Definition: dest.h:99
@ 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:103
void ReadyForQuery(CommandDest dest)
Definition: dest.c:256
void EndReplicationCommand(const char *commandTag)
Definition: dest.c:205
void NullCommand(CommandDest dest)
Definition: dest.c:218
PGDLLIMPORT DestReceiver * None_Receiver
Definition: dest.c:96
void(* rStartup)(DestReceiver *self, int operation, TupleDesc typeinfo)
Definition: dest.h:121
void(* rShutdown)(DestReceiver *self)
Definition: dest.h:124
bool(* receiveSlot)(TupleTableSlot *slot, DestReceiver *self)
Definition: dest.h:118
void(* rDestroy)(DestReceiver *self)
Definition: dest.h:126
CommandDest mydest
Definition: dest.h:128