granicus.if.org Git - postgresql/blob - src/include/tcop/dest.h

   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-2016, 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         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 function
 104  *              pointers that the executor must call.
 105  *
 106  * Note: the receiveSlot routine must be passed a slot containing a TupleDesc
 107  * identical to the one given to the rStartup routine.
 108  * ----------------
 109  */
 110 typedef struct _DestReceiver DestReceiver;
 111
 112 struct _DestReceiver
 113 {
 114         /* Called for each tuple to be output: */
 115         void            (*receiveSlot) (TupleTableSlot *slot,
 116                                                                                         DestReceiver *self);
 117         /* Per-executor-run initialization and shutdown: */
 118         void            (*rStartup) (DestReceiver *self,
 119                                                                                  int operation,
 120                                                                                  TupleDesc typeinfo);
 121         void            (*rShutdown) (DestReceiver *self);
 122         /* Destroy the receiver object itself (if dynamically allocated) */
 123         void            (*rDestroy) (DestReceiver *self);
 124         /* CommandDest code for this receiver */
 125         CommandDest mydest;
 126         /* Private fields might appear beyond this point... */
 127 };
 128
 129 extern DestReceiver *None_Receiver;             /* permanent receiver for DestNone */
 130
 131 /* The primary destination management functions */
 132
 133 extern void BeginCommand(const char *commandTag, CommandDest dest);
 134 extern DestReceiver *CreateDestReceiver(CommandDest dest);
 135 extern void EndCommand(const char *commandTag, CommandDest dest);
 136
 137 /* Additional functions that go with destination management, more or less. */
 138
 139 extern void NullCommand(CommandDest dest);
 140 extern void ReadyForQuery(CommandDest dest);
 141
 142 #endif   /* DEST_H */