src/backend/tcop/dest.c

   1 /*-------------------------------------------------------------------------
   2  *
   3  * dest.c
   4  *        support for communication destinations
   5  *
   6  *
   7  * Portions Copyright (c) 1996-2008, PostgreSQL Global Development Group
   8  * Portions Copyright (c) 1994, Regents of the University of California
   9  *
  10  * IDENTIFICATION
  11  *        $PostgreSQL$
  12  *
  13  *-------------------------------------------------------------------------
  14  */
  15 /*
  16  *       INTERFACE ROUTINES
  17  *              BeginCommand - initialize the destination at start of command
  18  *              CreateDestReceiver - create tuple receiver object for destination
  19  *              EndCommand - clean up the destination at end of command
  20  *              NullCommand - tell dest that an empty query string was recognized
  21  *              ReadyForQuery - tell dest that we are ready for a new query
  22  *
  23  *       NOTES
  24  *              These routines do the appropriate work before and after
  25  *              tuples are returned by a query to keep the backend and the
  26  *              "destination" portals synchronized.
  27  */
  28
  29 #include "postgres.h"
  30
  31 #include "access/printtup.h"
  32 #include "access/xact.h"
  33 #include "commands/copy.h"
  34 #include "executor/executor.h"
  35 #include "executor/tstoreReceiver.h"
  36 #include "libpq/libpq.h"
  37 #include "libpq/pqformat.h"
  38 #include "utils/portal.h"
  39
  40
  41 /* ----------------
  42  *              dummy DestReceiver functions
  43  * ----------------
  44  */
  45 static void
  46 donothingReceive(TupleTableSlot *slot, DestReceiver *self)
  47 {
  48 }
  49
  50 static void
  51 donothingStartup(DestReceiver *self, int operation, TupleDesc typeinfo)
  52 {
  53 }
  54
  55 static void
  56 donothingCleanup(DestReceiver *self)
  57 {
  58         /* this is used for both shutdown and destroy methods */
  59 }
  60
  61 /* ----------------
  62  *              static DestReceiver structs for dest types needing no local state
  63  * ----------------
  64  */
  65 static DestReceiver donothingDR = {
  66         donothingReceive, donothingStartup, donothingCleanup, donothingCleanup,
  67         DestNone
  68 };
  69
  70 static DestReceiver debugtupDR = {
  71         debugtup, debugStartup, donothingCleanup, donothingCleanup,
  72         DestDebug
  73 };
  74
  75 static DestReceiver spi_printtupDR = {
  76         spi_printtup, spi_dest_startup, donothingCleanup, donothingCleanup,
  77         DestSPI
  78 };
  79
  80 /* Globally available receiver for DestNone */
  81 DestReceiver *None_Receiver = &donothingDR;
  82
  83
  84 /* ----------------
  85  *              BeginCommand - initialize the destination at start of command
  86  * ----------------
  87  */
  88 void
  89 BeginCommand(const char *commandTag, CommandDest dest)
  90 {
  91         /* Nothing to do at present */
  92 }
  93
  94 /* ----------------
  95  *              CreateDestReceiver - return appropriate receiver function set for dest
  96  *
  97  * Note: a Portal must be specified for destinations DestRemote,
  98  * DestRemoteExecute, and DestTuplestore.  It can be NULL for the others.
  99  * ----------------
 100  */
 101 DestReceiver *
 102 CreateDestReceiver(CommandDest dest, Portal portal)
 103 {
 104         switch (dest)
 105         {
 106                 case DestRemote:
 107                 case DestRemoteExecute:
 108                         if (portal == NULL)
 109                                 elog(ERROR, "no portal specified for DestRemote receiver");
 110                         return printtup_create_DR(dest, portal);
 111
 112                 case DestNone:
 113                         return &donothingDR;
 114
 115                 case DestDebug:
 116                         return &debugtupDR;
 117
 118                 case DestSPI:
 119                         return &spi_printtupDR;
 120
 121                 case DestTuplestore:
 122                         if (portal == NULL)
 123                                 elog(ERROR, "no portal specified for DestTuplestore receiver");
 124                         if (portal->holdStore == NULL ||
 125                                 portal->holdContext == NULL)
 126                                 elog(ERROR, "portal has no holdStore");
 127                         return CreateTuplestoreDestReceiver(portal->holdStore,
 128                                                                                                 portal->holdContext);
 129
 130                 case DestIntoRel:
 131                         return CreateIntoRelDestReceiver();
 132
 133                 case DestCopyOut:
 134                         return CreateCopyDestReceiver();
 135         }
 136
 137         /* should never get here */
 138         return &donothingDR;
 139 }
 140
 141 /* ----------------
 142  *              EndCommand - clean up the destination at end of command
 143  * ----------------
 144  */
 145 void
 146 EndCommand(const char *commandTag, CommandDest dest)
 147 {
 148         switch (dest)
 149         {
 150                 case DestRemote:
 151                 case DestRemoteExecute:
 152                         pq_puttextmessage('C', commandTag);
 153                         break;
 154
 155                 case DestNone:
 156                 case DestDebug:
 157                 case DestSPI:
 158                 case DestTuplestore:
 159                 case DestIntoRel:
 160                 case DestCopyOut:
 161                         break;
 162         }
 163 }
 164
 165 /* ----------------
 166  *              NullCommand - tell dest that an empty query string was recognized
 167  *
 168  *              In FE/BE protocol version 1.0, this hack is necessary to support
 169  *              libpq's crufty way of determining whether a multiple-command
 170  *              query string is done.  In protocol 2.0 it's probably not really
 171  *              necessary to distinguish empty queries anymore, but we still do it
 172  *              for backwards compatibility with 1.0.  In protocol 3.0 it has some
 173  *              use again, since it ensures that there will be a recognizable end
 174  *              to the response to an Execute message.
 175  * ----------------
 176  */
 177 void
 178 NullCommand(CommandDest dest)
 179 {
 180         switch (dest)
 181         {
 182                 case DestRemote:
 183                 case DestRemoteExecute:
 184
 185                         /*
 186                          * tell the fe that we saw an empty query string.  In protocols
 187                          * before 3.0 this has a useless empty-string message body.
 188                          */
 189                         if (PG_PROTOCOL_MAJOR(FrontendProtocol) >= 3)
 190                                 pq_putemptymessage('I');
 191                         else
 192                                 pq_puttextmessage('I', "");
 193                         break;
 194
 195                 case DestNone:
 196                 case DestDebug:
 197                 case DestSPI:
 198                 case DestTuplestore:
 199                 case DestIntoRel:
 200                 case DestCopyOut:
 201                         break;
 202         }
 203 }
 204
 205 /* ----------------
 206  *              ReadyForQuery - tell dest that we are ready for a new query
 207  *
 208  *              The ReadyForQuery message is sent in protocol versions 2.0 and up
 209  *              so that the FE can tell when we are done processing a query string.
 210  *              In versions 3.0 and up, it also carries a transaction state indicator.
 211  *
 212  *              Note that by flushing the stdio buffer here, we can avoid doing it
 213  *              most other places and thus reduce the number of separate packets sent.
 214  * ----------------
 215  */
 216 void
 217 ReadyForQuery(CommandDest dest)
 218 {
 219         switch (dest)
 220         {
 221                 case DestRemote:
 222                 case DestRemoteExecute:
 223                         if (PG_PROTOCOL_MAJOR(FrontendProtocol) >= 3)
 224                         {
 225                                 StringInfoData buf;
 226
 227                                 pq_beginmessage(&buf, 'Z');
 228                                 pq_sendbyte(&buf, TransactionBlockStatusCode());
 229                                 pq_endmessage(&buf);
 230                         }
 231                         else if (PG_PROTOCOL_MAJOR(FrontendProtocol) >= 2)
 232                                 pq_putemptymessage('Z');
 233                         /* Flush output at end of cycle in any case. */
 234                         pq_flush();
 235                         break;
 236
 237                 case DestNone:
 238                 case DestDebug:
 239                 case DestSPI:
 240                 case DestTuplestore:
 241                 case DestIntoRel:
 242                 case DestCopyOut:
 243                         break;
 244         }
 245 }