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-2018, 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