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  * The DestReceiver object returned by CreateDestReceiver may be a statically
  39  * allocated object (for destination types that require no local state),
  40  * in which case rDestroy is a no-op.  Alternatively it can be a palloc'd
  41  * object that has DestReceiver as its first field and contains additional
  42  * fields (see printtup.c for an example).      These additional fields are then
  43  * accessible to the DestReceiver functions by casting the DestReceiver*
  44  * pointer passed to them.      The palloc'd object is pfree'd by the rDestroy
  45  * method.      Note that the caller of CreateDestReceiver should take care to
  46  * do so in a memory context that is long-lived enough for the receiver
  47  * object not to disappear while still needed.
  48  *
  49  * Special provision: None_Receiver is a permanently available receiver
  50  * object for the DestNone destination.  This avoids useless creation/destroy
  51  * calls in portal and cursor manipulations.
  52  *
  53  *
  54  * Portions Copyright (c) 1996-2008, PostgreSQL Global Development Group
  55  * Portions Copyright (c) 1994, Regents of the University of California
  56  *
  57  * $PostgreSQL$
  58  *
  59  *-------------------------------------------------------------------------
  60  */
  61 #ifndef DEST_H
  62 #define DEST_H
  63
  64 #include "executor/tuptable.h"
  65
  66
  67 /* buffer size to use for command completion tags */
  68 #define COMPLETION_TAG_BUFSIZE  64
  69
  70
  71 /* ----------------
  72  *              CommandDest is a simplistic means of identifying the desired
  73  *              destination.  Someday this will probably need to be improved.
  74  *
  75  * Note: only the values DestNone, DestDebug, DestRemote are legal for the
  76  * global variable whereToSendOutput.   The other values may be used
  77  * as the destination for individual commands.
  78  * ----------------
  79  */
  80 typedef enum
  81 {
  82         DestNone,                                       /* results are discarded */
  83         DestDebug,                                      /* results go to debugging output */
  84         DestRemote,                                     /* results sent to frontend process */
  85         DestRemoteExecute,                      /* sent to frontend, in Execute command */
  86         DestSPI,                                        /* results sent to SPI manager */
  87         DestTuplestore,                         /* results sent to Tuplestore */
  88         DestIntoRel,                            /* results sent to relation (SELECT INTO) */
  89         DestCopyOut,                            /* results sent to COPY TO code */
  90         DestSQLFunction                         /* results sent to SQL-language func mgr */
  91 } CommandDest;
  92
  93 /* ----------------
  94  *              DestReceiver is a base type for destination-specific local state.
  95  *              In the simplest cases, there is no state info, just the function
  96  *              pointers that the executor must call.
  97  *
  98  * Note: the receiveSlot routine must be passed a slot containing a TupleDesc
  99  * identical to the one given to the rStartup routine.
 100  * ----------------
 101  */
 102 typedef struct _DestReceiver DestReceiver;
 103
 104 struct _DestReceiver
 105 {
 106         /* Called for each tuple to be output: */
 107         void            (*receiveSlot) (TupleTableSlot *slot,
 108                                                                                         DestReceiver *self);
 109         /* Per-executor-run initialization and shutdown: */
 110         void            (*rStartup) (DestReceiver *self,
 111                                                                                  int operation,
 112                                                                                  TupleDesc typeinfo);
 113         void            (*rShutdown) (DestReceiver *self);
 114         /* Destroy the receiver object itself (if dynamically allocated) */
 115         void            (*rDestroy) (DestReceiver *self);
 116         /* CommandDest code for this receiver */
 117         CommandDest mydest;
 118         /* Private fields might appear beyond this point... */
 119 };
 120
 121 extern DestReceiver *None_Receiver;             /* permanent receiver for DestNone */
 122
 123 /* This is a forward reference to utils/portal.h */
 124
 125 typedef struct PortalData *Portal;
 126
 127 /* The primary destination management functions */
 128
 129 extern void BeginCommand(const char *commandTag, CommandDest dest);
 130 extern DestReceiver *CreateDestReceiver(CommandDest dest, Portal portal);
 131 extern void EndCommand(const char *commandTag, CommandDest dest);
 132
 133 /* Additional functions that go with destination management, more or less. */
 134
 135 extern void NullCommand(CommandDest dest);
 136 extern void ReadyForQuery(CommandDest dest);
 137
 138 #endif   /* DEST_H */