/* -------------------------------------------------------------------------
 *
 * tuptable.h
 *	  tuple table support stuff
 *
 *
 * Portions Copyright (c) 1996-2012, PostgreSQL Global Development Group
 * Portions Copyright (c) 1994, Regents of the University of California
 *
 * src/include/executor/tuptable.h
 *
 * -------------------------------------------------------------------------
 */
#ifndef TUPTABLE_H
#define TUPTABLE_H

#include "access/htup.h"
#include "storage/buf/buf.h"

#ifndef FRONTEND_PARSER
/* ----------
 * The executor stores tuples in a "tuple table" which is a List of
 * independent TupleTableSlots.  There are several cases we need to handle:
 *		1. physical tuple in a disk buffer page
 *		2. physical tuple constructed in palloc'ed memory
 *		3. "minimal" physical tuple constructed in palloc'ed memory
 *		4. "virtual" tuple consisting of Datum/isnull arrays
 *
 * The first two cases are similar in that they both deal with "materialized"
 * tuples, but resource management is different.  For a tuple in a disk page
 * we need to hold a pin on the buffer until the TupleTableSlot's reference
 * to the tuple is dropped; while for a palloc'd tuple we usually want the
 * tuple pfree'd when the TupleTableSlot's reference is dropped.
 *
 * A "minimal" tuple is handled similarly to a palloc'd regular tuple.
 * At present, minimal tuples never are stored in buffers, so there is no
 * parallel to case 1.	Note that a minimal tuple has no "system columns".
 * (Actually, it could have an OID, but we have no need to access the OID.)
 *
 * A "virtual" tuple is an optimization used to minimize physical data
 * copying in a nest of plan nodes.  Any pass-by-reference Datums in the
 * tuple point to storage that is not directly associated with the
 * TupleTableSlot; generally they will point to part of a tuple stored in
 * a lower plan node's output TupleTableSlot, or to a function result
 * constructed in a plan node's per-tuple econtext.  It is the responsibility
 * of the generating plan node to be sure these resources are not released
 * for as long as the virtual tuple needs to be valid.	We only use virtual
 * tuples in the result slots of plan nodes --- tuples to be copied anywhere
 * else need to be "materialized" into physical tuples.  Note also that a
 * virtual tuple does not have any "system columns".
 *
 * It is also possible for a TupleTableSlot to hold both physical and minimal
 * copies of a tuple.  This is done when the slot is requested to provide
 * the format other than the one it currently holds.  (Originally we attempted
 * to handle such requests by replacing one format with the other, but that
 * had the fatal defect of invalidating any pass-by-reference Datums pointing
 * into the existing slot contents.)  Both copies must contain identical data
 * payloads when this is the case.
 *
 * The Datum/isnull arrays of a TupleTableSlot serve double duty.  When the
 * slot contains a virtual tuple, they are the authoritative data.	When the
 * slot contains a physical tuple, the arrays contain data extracted from
 * the tuple.  (In this state, any pass-by-reference Datums point into
 * the physical tuple.)  The extracted information is built "lazily",
 * ie, only as needed.	This serves to avoid repeated extraction of data
 * from the physical tuple.
 *
 * A TupleTableSlot can also be "empty", indicated by flag TTS_EMPTY set in
 * tts_flags, holding no valid data.  This is the only valid state for a
 * freshly-created slot that has not yet had a tuple descriptor assigned to it.
 * In this state, TTS_SHOULDFREE should not be set in tts_flag, tts_tuple must
 * be NULL, tts_buffer InvalidBuffer, and tts_nvalid zero.
 *
 * The tupleDescriptor is simply referenced, not copied, by the TupleTableSlot
 * code.  The caller of ExecSetSlotDescriptor() is responsible for providing
 * a descriptor that will live as long as the slot does.  (Typically, both
 * slots and descriptors are in per-query memory and are freed by memory
 * context deallocation at query end; so it's not worth providing any extra
 * mechanism to do more.  However, the slot will increment the tupdesc
 * reference count if a reference-counted tupdesc is supplied.)
 *
 * When TTS_SHOULDFREE is set in tts_flags, the physical tuple is "owned" by
 * the slot and should be freed when the slot's reference to the tuple is
 * dropped.
 *
 * If tts_buffer is not InvalidBuffer, then the slot is holding a pin
 * on the indicated buffer page; drop the pin when we release the
 * slot's reference to that buffer.  (tts_shouldFree should always be
 * false in such a case, since presumably tts_tuple is pointing at the
 * buffer page.)
 *
 * tts_nvalid indicates the number of valid columns in the tts_values/isnull
 * arrays.	When the slot is holding a "virtual" tuple this must be equal
 * to the descriptor's natts.  When the slot is holding a physical tuple
 * this is equal to the number of columns we have extracted (we always
 * extract columns from left to right, so there are no holes).
 *
 * tts_values/tts_isnull are allocated when a descriptor is assigned to the
 * slot; they are of length equal to the descriptor's natts.
 *
 * tts_mintuple must always be NULL if the slot does not hold a "minimal"
 * tuple.  When it does, tts_mintuple points to the actual MinimalTupleData
 * object (the thing to be pfree'd if tts_shouldFreeMin is true).  If the slot
 * has only a minimal and not also a regular physical tuple, then tts_tuple
 * points at tts_minhdr and the fields of that struct are set correctly
 * for access to the minimal tuple; in particular, tts_minhdr.t_data points
 * MINIMAL_TUPLE_OFFSET bytes before tts_mintuple.	This allows column
 * extraction to treat the case identically to regular physical tuples.
 *
 * TTS_SLOW flag in tts_flags and tts_off are saved state for
 * slot_deform_tuple, and should not be touched by any other code.
 * ----------
 */

/* true = slot is empty */
#define TTS_FLAG_EMPTY (1 << 1)
#define TTS_EMPTY(slot) (((slot)->tts_flags & TTS_FLAG_EMPTY) != 0)

/* should pfree tts_tuple? */
#define TTS_FLAG_SHOULDFREE (1 << 2)
#define TTS_SHOULDFREE(slot) (((slot)->tts_flags & TTS_FLAG_SHOULDFREE) != 0)

/* should pfree tts_mintuple? */
#define TTS_FLAG_SHOULDFREEMIN (1 << 3)
#define TTS_SHOULDFREEMIN(slot) (((slot)->tts_flags & TTS_FLAG_SHOULDFREEMIN) != 0)

/* saved state for slot_deform_tuple */
#define TTS_FLAG_SLOW (1 << 4)
#define TTS_SLOW(slot) (((slot)->tts_flags & TTS_FLAG_SLOW) != 0)

/* openGauss flags */

/* should pfree should pfree tts_dataRow? */
#define TTS_FLAG_SHOULDFREE_ROW (1 << 12)
#define TTS_SHOULDFREE_ROW(slot) (((slot)->tts_flags & TTS_FLAG_SHOULDFREE_ROW) != 0)

typedef struct TupleTableSlot {
    NodeTag type;
    uint16 tts_flags;   /* Boolean states */
    int tts_nvalid;     /* # of valid values in tts_values */
    const TableAmRoutine* tts_tam_ops; /* implementation of table AM */
    Tuple tts_tuple;    /* physical tuple, or NULL if virtual */

    TupleDesc tts_tupleDescriptor; /* slot's tuple descriptor */
    MemoryContext tts_mcxt;        /* slot itself is in this context */
    Buffer tts_buffer;             /* tuple's buffer, or InvalidBuffer */
    long tts_off;                  /* saved state for slot_deform_tuple */
    Datum* tts_values;             /* current per-attribute values */
    bool* tts_isnull;              /* current per-attribute isnull flags */
    
    MinimalTuple tts_mintuple;     /* minimal tuple, or NULL if none */
    HeapTupleData tts_minhdr;      /* workspace for minimal-tuple-only case */
    
    long tts_meta_off;             /* saved state for slot_deform_cmpr_tuple */
    Datum* tts_lobPointers;
#ifdef PGXC
    /*
     * PGXC extension to support tuples sent from remote Datanode.
     */
    char* tts_dataRow;                   /* Tuple data in DataRow format */
    int tts_dataLen;                     /* Actual length of the data row */
    struct AttInMetadata* tts_attinmeta; /* store here info to extract values from the DataRow */
    Oid tts_xcnodeoid;                   /* Oid of node from where the datarow is fetched */
    MemoryContext tts_per_tuple_mcxt;
#endif
    bool tts_ndpAggHandled;              /* slot is from ndp backend, handled by aggregate */
} TupleTableSlot;

#define TTS_HAS_PHYSICAL_TUPLE(slot) ((slot)->tts_tuple != NULL && (slot)->tts_tuple != &((slot)->tts_minhdr))


#define TTS_TABLEAM_IS_HEAP(slot) ((slot)->tts_tam_ops == TableAmHeap)
#define TTS_TABLEAM_IS_USTORE(slot) ((slot)->tts_tam_ops == TableAmUstore)

/*
 * TupIsNull -- is a TupleTableSlot empty?
 */
#define TupIsNull(slot) ((slot) == NULL || TTS_EMPTY(slot))

/* in executor/execTuples.c */
extern TupleTableSlot* MakeTupleTableSlot(bool has_tuple_mcxt = false, const TableAmRoutine* tam_ops = TableAmHeap);
extern TupleTableSlot* ExecAllocTableSlot(List** tupleTable, const TableAmRoutine* tam_ops = TableAmHeap);
extern void ExecResetTupleTable(List* tupleTable, bool shouldFree);
extern TupleTableSlot* MakeSingleTupleTableSlot(TupleDesc tupdesc, bool allocSlotCxt = false, const TableAmRoutine* tam_ops = TableAmHeap);
extern void ExecDropSingleTupleTableSlot(TupleTableSlot* slot);
extern void ExecSetSlotDescriptor(TupleTableSlot* slot, TupleDesc tupdesc);
extern TupleTableSlot* ExecStoreTuple(Tuple tuple, TupleTableSlot* slot, Buffer buffer, bool shouldFree);
extern TupleTableSlot *ExecStoreTupleBatch(HeapTuple tuple, TupleTableSlot *slot,
    Buffer buffer, bool shouldFree, int rownum);
extern TupleTableSlot* ExecStoreMinimalTuple(MinimalTuple mtup, TupleTableSlot* slot, bool shouldFree);

#ifdef PGXC
extern TupleTableSlot* ExecStoreDataRowTuple(
    char* msg, size_t len, Oid msgnode_oid, TupleTableSlot* slot, bool shouldFree);
#endif
extern TupleTableSlot* ExecClearTuple(TupleTableSlot* slot);
extern void ExecClearMutilTuple(List* slots);

/* --------------------------------
 *		ExecStoreVirtualTuple
 *			Mark a slot as containing a virtual tuple.
 *
 * The protocol for loading a slot with virtual tuple data is:
 *		* Call ExecClearTuple to mark the slot empty.
 *		* Store data into the Datum/isnull arrays.
 *		* Call ExecStoreVirtualTuple to mark the slot valid.
 * This is a bit unclean but it avoids one round of data copying.
 * --------------------------------
 */
inline TupleTableSlot* ExecStoreVirtualTuple(TupleTableSlot* slot)
{
    /*
     * sanity checks
     */
    Assert(slot != NULL);
    Assert(slot->tts_tupleDescriptor != NULL);
    Assert(TTS_EMPTY(slot));

    slot->tts_flags &= ~TTS_FLAG_EMPTY;
    slot->tts_nvalid = slot->tts_tupleDescriptor->natts;

    return slot;
}

extern TupleTableSlot* ExecStoreAllNullTuple(TupleTableSlot* slot);
extern HeapTuple ExecCopySlotTuple(TupleTableSlot* slot);
extern MinimalTuple ExecCopySlotMinimalTuple(TupleTableSlot* slot, bool need_transform_anyarray = false);
extern HeapTuple ExecFetchSlotTuple(TupleTableSlot* slot);
extern MinimalTuple ExecFetchSlotMinimalTuple(TupleTableSlot* slot);
extern Datum ExecFetchSlotTupleDatum(TupleTableSlot* slot);
extern HeapTuple ExecMaterializeSlot(TupleTableSlot* slot);
extern TupleTableSlot* ExecCopySlot(TupleTableSlot* dstslot, TupleTableSlot* srcslot);

/* heap table specific slot/tuple operations*/
/* definitions are found in access/common/heaptuple.c */
extern void heap_slot_clear(TupleTableSlot* slot);
extern HeapTuple heap_slot_materialize(TupleTableSlot* slot);
extern MinimalTuple heap_slot_get_minimal_tuple(TupleTableSlot *slot);
extern MinimalTuple heap_slot_copy_minimal_tuple(TupleTableSlot *slot);
extern void heap_slot_store_minimal_tuple(MinimalTuple mtup, TupleTableSlot *slot, bool shouldFree);
extern HeapTuple heap_slot_get_heap_tuple (TupleTableSlot* slot);
extern HeapTuple heap_slot_copy_heap_tuple (TupleTableSlot *slot);
extern void heap_slot_store_heap_tuple(Tuple tup, TupleTableSlot* slot, Buffer buffer, bool shouldFree, bool batchMode);
extern Datum heap_slot_getattr(TupleTableSlot* slot, int attnum, bool* isnull, bool need_transform_anyarray = false);
extern void heap_slot_getallattrs(TupleTableSlot* slot, bool need_transform_anyarray = false);
extern void slot_getallattrsfast(TupleTableSlot *slot, int maxIdx);
extern void heap_slot_getsomeattrs(TupleTableSlot* slot, int attnum);
extern bool heap_slot_attisnull(TupleTableSlot* slot, int attnum);
extern void heap_slot_formbatch(TupleTableSlot* slot, struct VectorBatch* batch, int cur_rows, int attnum);


#ifdef USE_SPQ
extern Datum slot_getattr(TupleTableSlot *slot, int attnum, bool *isnull);
extern void slot_getsomeattrs(TupleTableSlot *slot, int attnum);
extern void slot_getallattrs(TupleTableSlot *slot);
extern Datum heap_copy_tuple_as_datum(HeapTuple tuple, TupleDesc tupleDesc);
#endif

#endif /* !FRONTEND_PARSER */
#endif /* TUPTABLE_H */