codekingpro/portable-devtools

1/*-------------------------------------------------------------------------2 *3 * dest.h4 *	  support for communication destinations5 *6 * Whenever the backend executes a query that returns tuples, the results7 * have to go someplace.  For example:8 *9 *	  - stdout is the destination only when we are running a10 *		standalone backend (no postmaster) and are returning results11 *		back to an interactive user.12 *13 *	  - a remote process is the destination when we are14 *		running a backend with a frontend and the frontend executes15 *		PQexec() or PQfn().  In this case, the results are sent16 *		to the frontend via the functions in backend/libpq.17 *18 *	  - DestNone is the destination when the system executes19 *		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-specific25 * 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 specified31 * destination.  The executor, as well as utility statements that can return32 * tuples, are passed the resulting DestReceiver* pointer.  Each executor run33 * or utility execution calls the receiver's rStartup method, then the34 * receiveSlot method (zero or more times), then the rShutdown method.35 * The same receiver object may be re-used multiple times; eventually it is36 * destroyed by calling its rDestroy method.37 *38 * In some cases, receiver objects require additional parameters that must39 * be passed to them after calling CreateDestReceiver.  Since the set of40 * parameters varies for different receiver types, this is not handled by41 * this module, but by direct calls from the calling code to receiver type42 * specific functions.43 *44 * The DestReceiver object returned by CreateDestReceiver may be a statically45 * 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'd47 * object that has DestReceiver as its first field and contains additional48 * fields (see printtup.c for an example).  These additional fields are then49 * accessible to the DestReceiver functions by casting the DestReceiver*50 * pointer passed to them.  The palloc'd object is pfree'd by the rDestroy51 * method.  Note that the caller of CreateDestReceiver should take care to52 * do so in a memory context that is long-lived enough for the receiver53 * object not to disappear while still needed.54 *55 * Special provision: None_Receiver is a permanently available receiver56 * object for the DestNone destination.  This avoids useless creation/destroy57 * calls in portal and cursor manipulations.58 *59 *60 * Portions Copyright (c) 1996-2023, PostgreSQL Global Development Group61 * Portions Copyright (c) 1994, Regents of the University of California62 *63 * src/include/tcop/dest.h64 *65 *-------------------------------------------------------------------------66 */67#ifndef DEST_H68#define DEST_H69 70#include "executor/tuptable.h"71#include "tcop/cmdtag.h"72 73 74 75 76/* ----------------77 *		CommandDest is a simplistic means of identifying the desired78 *		destination.  Someday this will probably need to be improved.79 *80 * Note: only the values DestNone, DestDebug, DestRemote are legal for the81 * global variable whereToSendOutput.   The other values may be used82 * as the destination for individual commands.83 * ----------------84 */85typedef enum86{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} CommandDest;100 101/* ----------------102 *		DestReceiver is a base type for destination-specific local state.103 *		In the simplest cases, there is no state info, just the function104 *		pointers that the executor must call.105 *106 * Note: the receiveSlot routine must be passed a slot containing a TupleDesc107 * identical to the one given to the rStartup routine.  It returns bool where108 * a "true" value means "continue processing" and a "false" value means109 * "stop early, just as if we'd reached the end of the scan".110 * ----------------111 */112typedef struct _DestReceiver DestReceiver;113 114struct _DestReceiver115{116	/* Called for each tuple to be output: */117	bool		(*receiveSlot) (TupleTableSlot *slot,118								DestReceiver *self);119	/* Per-executor-run initialization and shutdown: */120	void		(*rStartup) (DestReceiver *self,121							 int operation,122							 TupleDesc typeinfo);123	void		(*rShutdown) (DestReceiver *self);124	/* Destroy the receiver object itself (if dynamically allocated) */125	void		(*rDestroy) (DestReceiver *self);126	/* CommandDest code for this receiver */127	CommandDest mydest;128	/* Private fields might appear beyond this point... */129};130 131extern PGDLLIMPORT DestReceiver *None_Receiver; /* permanent receiver for132												 * DestNone */133 134/* The primary destination management functions */135 136extern void BeginCommand(CommandTag commandTag, CommandDest dest);137extern DestReceiver *CreateDestReceiver(CommandDest dest);138extern void EndCommand(const QueryCompletion *qc, CommandDest dest,139					   bool force_undecorated_output);140extern void EndReplicationCommand(const char *commandTag);141 142/* Additional functions that go with destination management, more or less. */143 144extern void NullCommand(CommandDest dest);145extern void ReadyForQuery(CommandDest dest);146 147#endif							/* DEST_H */148