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-2009, PostgreSQL Global Development Group
  61  * Portions Copyright (c) 1994, Regents of the University of California
  62  *
  63  * $PostgreSQL$
  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 } CommandDest;
  98
  99 /* ----------------
 100  *              DestReceiver is a base type for destination-specific local state.
 101  *              In the simplest cases, there is no state info, just the function
 102  *              pointers that the executor must call.
 103  *
 104  * Note: the receiveSlot routine must be passed a slot containing a TupleDesc
 105  * identical to the one given to the rStartup routine.
 106  * ----------------
 107  */
 108 typedef struct _DestReceiver DestReceiver;
 109
 110 struct _DestReceiver
 111 {
 112         /* Called for each tuple to be output: */
 113         void            (*receiveSlot) (TupleTableSlot *slot,
 114                                                                                         DestReceiver *self);
 115         /* Per-executor-run initialization and shutdown: */
 116         void            (*rStartup) (DestReceiver *self,
 117                                                                                  int operation,
 118                                                                                  TupleDesc typeinfo);
 119         void            (*rShutdown) (DestReceiver *self);
 120         /* Destroy the receiver object itself (if dynamically allocated) */
 121         void            (*rDestroy) (DestReceiver *self);
 122         /* CommandDest code for this receiver */
 123         CommandDest mydest;
 124         /* Private fields might appear beyond this point... */
 125 };
 126
 127 extern DestReceiver *None_Receiver;             /* permanent receiver for DestNone */
 128
 129 /* The primary destination management functions */
 130
 131 extern void BeginCommand(const char *commandTag, CommandDest dest);
 132 extern DestReceiver *CreateDestReceiver(CommandDest dest);
 133 extern void EndCommand(const char *commandTag, CommandDest dest);
 134
 135 /* Additional functions that go with destination management, more or less. */
 136
 137 extern void NullCommand(CommandDest dest);
 138 extern void ReadyForQuery(CommandDest dest);
 139
 140 #endif   /* DEST_H */