diff options
Diffstat (limited to 'src/include/tcop/dest.h')
| -rw-r--r-- | src/include/tcop/dest.h | 149 |
1 files changed, 149 insertions, 0 deletions
diff --git a/src/include/tcop/dest.h b/src/include/tcop/dest.h new file mode 100644 index 0000000..88a7e59 --- /dev/null +++ b/src/include/tcop/dest.h @@ -0,0 +1,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-2021, 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 */ |