dest.c

Go to the documentation of this file.

/*-------------------------------------------------------------------------
 *
 * 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;
    }
}