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-2017, 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 
72 
73 /* buffer size to use for command completion tags */
74 #define COMPLETION_TAG_BUFSIZE	64
75 
76 
77 /* ----------------
78  *		CommandDest is a simplistic means of identifying the desired
79  *		destination.  Someday this will probably need to be improved.
80  *
81  * Note: only the values DestNone, DestDebug, DestRemote are legal for the
82  * global variable whereToSendOutput.   The other values may be used
83  * as the destination for individual commands.
84  * ----------------
85  */
86 typedef enum
87 {
88 	DestNone,					/* results are discarded */
89 	DestDebug,					/* results go to debugging output */
90 	DestRemote,					/* results sent to frontend process */
91 	DestRemoteExecute,			/* sent to frontend, in Execute command */
92 	DestRemoteSimple,			/* sent to frontend, w/no catalog access */
93 	DestSPI,					/* results sent to SPI manager */
94 	DestTuplestore,				/* results sent to Tuplestore */
95 	DestIntoRel,				/* results sent to relation (SELECT INTO) */
96 	DestCopyOut,				/* results sent to COPY TO code */
97 	DestSQLFunction,			/* results sent to SQL-language func mgr */
98 	DestTransientRel,			/* results sent to transient relation */
99 	DestTupleQueue				/* results sent to tuple queue */
100 } CommandDest;
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  */
113 typedef struct _DestReceiver DestReceiver;
114 
115 struct _DestReceiver
116 {
117 	/* Called for each tuple to be output: */
118 	bool		(*receiveSlot) (TupleTableSlot *slot,
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 */
128 	CommandDest mydest;
129 	/* Private fields might appear beyond this point... */
130 };
131 
132 extern PGDLLIMPORT DestReceiver *None_Receiver; /* permanent receiver for
133 												 * DestNone */
134 
135 /* The primary destination management functions */
136 
137 extern void BeginCommand(const char *commandTag, CommandDest dest);
138 extern DestReceiver *CreateDestReceiver(CommandDest dest);
139 extern void EndCommand(const char *commandTag, CommandDest dest);
140 
141 /* Additional functions that go with destination management, more or less. */
142 
143 extern void NullCommand(CommandDest dest);
144 extern void ReadyForQuery(CommandDest dest);
145 
146 #endif							/* DEST_H */
147