/*-------------------------------------------------------------------------

 *

 * dest.c

 *    support for communication destinations

 *

 *

 * Portions Copyright (c) 1996-2026, PostgreSQL Global Development Group

 * Portions Copyright (c) 1994, Regents of the University of California

 *

 * IDENTIFICATION

 *    src/backend/tcop/dest.c

 *

 *-------------------------------------------------------------------------

 */

/*

 *   INTERFACE ROUTINES

 *    BeginCommand - initialize the destination at start of command

 *    CreateDestReceiver - create tuple receiver object for destination

 *    EndCommand - clean up the destination at end of command

 *    NullCommand - tell dest that an empty query string was recognized

 *    ReadyForQuery - tell dest that we are ready for a new query

 *

 *   NOTES

 *    These routines do the appropriate work before and after

 *    tuples are returned by a query to keep the backend and the

 *    "destination" portals synchronized.

 */

#include "postgres.h"

#include "access/printsimple.h"

#include "access/printtup.h"

#include "access/xact.h"

#include "commands/copy.h"

#include "commands/createas.h"

#include "commands/explain_dr.h"

#include "commands/matview.h"

#include "executor/functions.h"

#include "executor/tqueue.h"

#include "executor/tstoreReceiver.h"

#include "libpq/libpq.h"

#include "libpq/pqformat.h"

/* ----------------

 *    dummy DestReceiver functions

 * ----------------

 */

static bool

donothingReceive(TupleTableSlot *slot, DestReceiver *self)

{

  return true;

}

static void

donothingStartup(DestReceiver *self, int operation, TupleDesc typeinfo)

{

}

static void

donothingCleanup(DestReceiver *self)

{

  /* this is used for both shutdown and destroy methods */

}

/* ----------------

 *    static DestReceiver structs for dest types needing no local state

 * ----------------

 */

static const DestReceiver donothingDR = {

  donothingReceive, donothingStartup, donothingCleanup, donothingCleanup,

  DestNone

};

static const DestReceiver debugtupDR = {

  debugtup, debugStartup, donothingCleanup, donothingCleanup,

  DestDebug

};

static const DestReceiver printsimpleDR = {

  printsimple, printsimple_startup, donothingCleanup, donothingCleanup,

  DestRemoteSimple

};

static const DestReceiver spi_printtupDR = {

  spi_printtup, spi_dest_startup, donothingCleanup, donothingCleanup,

  DestSPI

};

/*

 * Globally available receiver for DestNone.

 *

 * It's ok to cast the constness away as any modification of the none receiver

 * would be a bug (which gets easier to catch this way).

 */

DestReceiver *None_Receiver = (DestReceiver *) &donothingDR;

/* ----------------

 *    BeginCommand - initialize the destination at start of command

 * ----------------

 */

void

BeginCommand(CommandTag commandTag, CommandDest dest)

{

  /* Nothing to do at present */

}

/* ----------------

 *    CreateDestReceiver - return appropriate receiver function set for dest

 * ----------------

 */

DestReceiver *

CreateDestReceiver(CommandDest dest)

{

  /*

   * It's ok to cast the constness away as any modification of the none

   * receiver would be a bug (which gets easier to catch this way).

   */

  switch (dest)

  {

    case DestRemote:

    case DestRemoteExecute:

      return printtup_create_DR(dest);

    case DestRemoteSimple:

      return unconstify(DestReceiver *, &printsimpleDR);

    case DestNone:

      return unconstify(DestReceiver *, &donothingDR);

    case DestDebug:

      return unconstify(DestReceiver *, &debugtupDR);

    case DestSPI:

      return unconstify(DestReceiver *, &spi_printtupDR);

    case DestTuplestore:

      return CreateTuplestoreDestReceiver();

    case DestIntoRel:

      return CreateIntoRelDestReceiver(NULL);

    case DestCopyOut:

      return CreateCopyDestReceiver();

    case DestSQLFunction:

      return CreateSQLFunctionDestReceiver();

    case DestTransientRel:

      return CreateTransientRelDestReceiver(InvalidOid);

    case DestTupleQueue:

      return CreateTupleQueueDestReceiver(NULL);

    case DestExplainSerialize:

      return CreateExplainSerializeDestReceiver(NULL);

  }

  /* should never get here */

  pg_unreachable();

}

/* ----------------

 *    EndCommand - clean up the destination at end of command

 * ----------------

 */

void

EndCommandExtended(const QueryCompletion *qc, CommandDest dest,

           bool force_undecorated_output, bool noblock)

{

  char    completionTag[COMPLETION_TAG_BUFSIZE];

  Size    len;

  switch (dest)

  {

    case DestRemote:

    case DestRemoteExecute:

    case DestRemoteSimple:

      len = BuildQueryCompletionString(completionTag, qc,

                       force_undecorated_output);

      if (noblock)

        pq_putmessage_noblock(PqMsg_CommandComplete, completionTag, len + 1);

      else

        pq_putmessage(PqMsg_CommandComplete, completionTag, len + 1);

      break;

    case DestNone:

    case DestDebug:

    case DestSPI:

    case DestTuplestore:

    case DestIntoRel:

    case DestCopyOut:

    case DestSQLFunction:

    case DestTransientRel:

    case DestTupleQueue:

    case DestExplainSerialize:

      break;

  }

}

void

EndCommand(const QueryCompletion *qc, CommandDest dest, bool force_undecorated_output)

{

  EndCommandExtended(qc, dest, force_undecorated_output, false);

}

/* ----------------

 *    EndReplicationCommand - stripped down version of EndCommand

 *

 *    For use by replication commands.

 * ----------------

 */

void

EndReplicationCommand(const char *commandTag)

{

  pq_putmessage(PqMsg_CommandComplete, commandTag, strlen(commandTag) + 1);

}

/* ----------------

 *    NullCommand - tell dest that an empty query string was recognized

 *

 *    This ensures that there will be a recognizable end to the response

 *    to an Execute message in the extended query protocol.

 * ----------------

 */

void

NullCommand(CommandDest dest)

{

  switch (dest)

  {

    case DestRemote:

    case DestRemoteExecute:

    case DestRemoteSimple:

      /* Tell the FE that we saw an empty query string */

      pq_putemptymessage(PqMsg_EmptyQueryResponse);

      break;

    case DestNone:

    case DestDebug:

    case DestSPI:

    case DestTuplestore:

    case DestIntoRel:

    case DestCopyOut:

    case DestSQLFunction:

    case DestTransientRel:

    case DestTupleQueue:

    case DestExplainSerialize:

      break;

  }

}

/* ----------------

 *    ReadyForQuery - tell dest that we are ready for a new query

 *

 *    The ReadyForQuery message is sent so that the FE can tell when

 *    we are done processing a query string.

 *    In versions 3.0 and up, it also carries a transaction state indicator.

 *

 *    Note that by flushing the stdio buffer here, we can avoid doing it

 *    most other places and thus reduce the number of separate packets sent.

 * ----------------

 */

void

ReadyForQuery(CommandDest dest)

{

  switch (dest)

  {

    case DestRemote:

    case DestRemoteExecute:

    case DestRemoteSimple:

      {

        StringInfoData buf;

        pq_beginmessage(&buf, PqMsg_ReadyForQuery);

        pq_sendbyte(&buf, TransactionBlockStatusCode());

        pq_endmessage(&buf);

      }

      /* Flush output at end of cycle in any case. */

      pq_flush();

      break;

    case DestNone:

    case DestDebug:

    case DestSPI:

    case DestTuplestore:

    case DestIntoRel:

    case DestCopyOut:

    case DestSQLFunction:

    case DestTransientRel:

    case DestTupleQueue:

    case DestExplainSerialize:

      break;

  }

}