/src/postgres/src/include/executor/tuptable.h

Source
/*-------------------------------------------------------------------------
 *
 * tuptable.h
 *    tuple table support stuff
 *
 *
 * Portions Copyright (c) 1996-2026, 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 "access/sysattr.h"
#include "access/tupdesc.h"
#include "storage/buf.h"

/*----------
 * The executor stores tuples in a "tuple table" which is a List of
 * independent TupleTableSlots.
 *
 * There's various different types of tuple table slots, each being able to
 * store different types of tuples. Additional types of slots can be added
 * without modifying core code. The type of a slot is determined by the
 * TupleTableSlotOps* passed to the slot creation routine. The builtin types
 * of slots are
 *
 * 1. physical tuple in a disk buffer page (TTSOpsBufferHeapTuple)
 * 2. physical tuple constructed in palloc'ed memory (TTSOpsHeapTuple)
 * 3. "minimal" physical tuple constructed in palloc'ed memory
 *    (TTSOpsMinimalTuple)
 * 4. "virtual" tuple consisting of Datum/isnull arrays (TTSOpsVirtual)
 *
 *
 * 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".
 *
 * A "virtual" tuple is an optimization used to minimize physical data copying
 * in a nest of plan nodes.  Until materialized pass-by-reference Datums in
 * the slot 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 or is materialized.  Note
 * also that a virtual tuple does not have any "system columns".
 *
 * The Datum/isnull arrays of a TupleTableSlot serve double duty.  For virtual
 * slots they are the authoritative data.  For the other builtin slots,
 * 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_FLAG_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_FLAG_SHOULDFREE should not be set in tts_flags and
 * tts_nvalid should be set to 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_FLAG_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.
 *
 * tts_values/tts_isnull are allocated either when the slot is created (when
 * the descriptor is provided), or when a descriptor is assigned to the slot;
 * they are of length equal to the descriptor's natts.
 *----------
 */

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

/* should pfree tuple "owned" by the slot? */
#define     TTS_FLAG_SHOULDFREE   (1 << 2)
#define TTS_SHOULDFREE(slot) (((slot)->tts_flags & TTS_FLAG_SHOULDFREE) != 0)

/*
 * true = slot's formed tuple guaranteed to not have NULLs in NOT NULLable
 * columns.
 */
#define     TTS_FLAG_OBEYS_NOT_NULL_CONSTRAINTS   (1 << 3)
#define TTS_OBEYS_NOT_NULL_CONSTRAINTS(slot) \
  (((slot)->tts_flags & TTS_FLAG_OBEYS_NOT_NULL_CONSTRAINTS) != 0)

/* fixed tuple descriptor */
#define     TTS_FLAG_FIXED    (1 << 4)
#define TTS_FIXED(slot) (((slot)->tts_flags & TTS_FLAG_FIXED) != 0)

/*
 * Defines which of the above flags should never be set in tts_flags when the
 * TupleTableSlot is created.
 */
#define     TTS_FLAGS_TRANSIENT (TTS_FLAG_EMPTY|TTS_FLAG_SHOULDFREE)

struct TupleTableSlotOps;
typedef struct TupleTableSlotOps TupleTableSlotOps;

/* base tuple table slot type */
typedef struct TupleTableSlot
{
  NodeTag   type;
#define FIELDNO_TUPLETABLESLOT_FLAGS 1
  uint16    tts_flags;    /* Boolean states */
#define FIELDNO_TUPLETABLESLOT_NVALID 2
  AttrNumber  tts_nvalid;   /* # of valid values in tts_values */
  const TupleTableSlotOps *const tts_ops; /* implementation of slot */
#define FIELDNO_TUPLETABLESLOT_TUPLEDESCRIPTOR 4
  TupleDesc tts_tupleDescriptor;  /* slot's tuple descriptor */
#define FIELDNO_TUPLETABLESLOT_VALUES 5
  Datum    *tts_values;   /* current per-attribute values */
#define FIELDNO_TUPLETABLESLOT_ISNULL 6
  bool     *tts_isnull;   /* current per-attribute isnull flags.  Array
                 * size must always be rounded up to the next
                 * multiple of 8 elements. */
  int     tts_first_nonguaranteed;  /* The value from the TupleDesc's
                       * firstNonGuaranteedAttr, or 0
                       * when tts_flags does not contain
                       * TTS_FLAG_OBEYS_NOT_NULL_CONSTRAINTS */

  MemoryContext tts_mcxt;   /* slot itself is in this context */
  ItemPointerData tts_tid;  /* stored tuple's tid */
  Oid     tts_tableOid; /* table oid of tuple */
} TupleTableSlot;

/* routines for a TupleTableSlot implementation */
struct TupleTableSlotOps
{
  /* Minimum size of the slot */
  size_t    base_slot_size;

  /* Initialization. */
  void    (*init) (TupleTableSlot *slot);

  /* Destruction. */
  void    (*release) (TupleTableSlot *slot);

  /*
   * Clear the contents of the slot. Only the contents are expected to be
   * cleared and not the tuple descriptor. Typically an implementation of
   * this callback should free the memory allocated for the tuple contained
   * in the slot.
   */
  void    (*clear) (TupleTableSlot *slot);

  /*
   * Fill up first natts entries of tts_values and tts_isnull arrays with
   * values from the tuple contained in the slot and set the slot's
   * tts_nvalid to natts. The function may be called with an natts value
   * more than the number of attributes available in the tuple, in which
   * case the function must call slot_getmissingattrs() to populate the
   * remaining attributes.  The function must raise an ERROR if 'natts' is
   * higher than the number of attributes in the slot's TupleDesc.
   */
  void    (*getsomeattrs) (TupleTableSlot *slot, int natts);

  /*
   * Returns value of the given system attribute as a datum and sets isnull
   * to false, if it's not NULL. Throws an error if the slot type does not
   * support system attributes.
   */
  Datum   (*getsysattr) (TupleTableSlot *slot, int attnum, bool *isnull);

  /*
   * Check if the tuple is created by the current transaction. Throws an
   * error if the slot doesn't contain the storage tuple.
   */
  bool    (*is_current_xact_tuple) (TupleTableSlot *slot);

  /*
   * Make the contents of the slot solely depend on the slot, and not on
   * underlying resources (like another memory context, buffers, etc).
   */
  void    (*materialize) (TupleTableSlot *slot);

  /*
   * Copy the contents of the source slot into the destination slot's own
   * context. Invoked using callback of the destination slot.  'dstslot' and
   * 'srcslot' can be assumed to have the same number of attributes.
   */
  void    (*copyslot) (TupleTableSlot *dstslot, TupleTableSlot *srcslot);

  /*
   * Return a heap tuple "owned" by the slot. It is slot's responsibility to
   * free the memory consumed by the heap tuple. If the slot can not "own" a
   * heap tuple, it should not implement this callback and should set it as
   * NULL.
   */
  HeapTuple (*get_heap_tuple) (TupleTableSlot *slot);

  /*
   * Return a minimal tuple "owned" by the slot. It is slot's responsibility
   * to free the memory consumed by the minimal tuple. If the slot can not
   * "own" a minimal tuple, it should not implement this callback and should
   * set it as NULL.
   */
  MinimalTuple (*get_minimal_tuple) (TupleTableSlot *slot);

  /*
   * Return a copy of heap tuple representing the contents of the slot. The
   * copy needs to be palloc'd in the current memory context. The slot
   * itself is expected to remain unaffected. It is *not* expected to have
   * meaningful "system columns" in the copy. The copy is not be "owned" by
   * the slot i.e. the caller has to take responsibility to free memory
   * consumed by the slot.
   */
  HeapTuple (*copy_heap_tuple) (TupleTableSlot *slot);

  /*
   * Return a copy of minimal tuple representing the contents of the slot.
   * The copy needs to be palloc'd in the current memory context. The slot
   * itself is expected to remain unaffected. It is *not* expected to have
   * meaningful "system columns" in the copy. The copy is not be "owned" by
   * the slot i.e. the caller has to take responsibility to free memory
   * consumed by the slot.
   *
   * The copy has "extra" bytes (maxaligned and zeroed) available before the
   * tuple, which is useful so that some callers may store extra data along
   * with the minimal tuple without the need for an additional allocation.
   */
  MinimalTuple (*copy_minimal_tuple) (TupleTableSlot *slot, Size extra);
};

/*
 * Predefined TupleTableSlotOps for various types of TupleTableSlotOps. The
 * same are used to identify the type of a given slot.
 */
extern PGDLLIMPORT const TupleTableSlotOps TTSOpsVirtual;
extern PGDLLIMPORT const TupleTableSlotOps TTSOpsHeapTuple;
extern PGDLLIMPORT const TupleTableSlotOps TTSOpsMinimalTuple;
extern PGDLLIMPORT const TupleTableSlotOps TTSOpsBufferHeapTuple;

#define TTS_IS_VIRTUAL(slot) ((slot)->tts_ops == &TTSOpsVirtual)
#define TTS_IS_HEAPTUPLE(slot) ((slot)->tts_ops == &TTSOpsHeapTuple)
#define TTS_IS_MINIMALTUPLE(slot) ((slot)->tts_ops == &TTSOpsMinimalTuple)
#define TTS_IS_BUFFERTUPLE(slot) ((slot)->tts_ops == &TTSOpsBufferHeapTuple)


/*
 * Tuple table slot implementations.
 */

typedef struct VirtualTupleTableSlot
{
  pg_node_attr(abstract)

  TupleTableSlot base;

  char     *data;     /* data for materialized slots */
} VirtualTupleTableSlot;

typedef struct HeapTupleTableSlot
{
  pg_node_attr(abstract)

  TupleTableSlot base;

#define FIELDNO_HEAPTUPLETABLESLOT_TUPLE 1
  HeapTuple tuple;      /* physical tuple */
#define FIELDNO_HEAPTUPLETABLESLOT_OFF 2
  uint32    off;      /* saved state for slot_deform_heap_tuple */
  HeapTupleData tupdata;    /* optional workspace for storing tuple */
} HeapTupleTableSlot;

/* heap tuple residing in a buffer */
typedef struct BufferHeapTupleTableSlot
{
  pg_node_attr(abstract)

  HeapTupleTableSlot base;

  /*
   * If 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_FLAG_SHOULDFREE should not be set in
   * such a case, since presumably base.tuple is pointing into the buffer.)
   */
  Buffer    buffer;     /* tuple's buffer, or InvalidBuffer */
} BufferHeapTupleTableSlot;

typedef struct MinimalTupleTableSlot
{
  pg_node_attr(abstract)

  TupleTableSlot base;

  /*
   * In a minimal slot tuple points at minhdr and the fields of that struct
   * are set correctly for access to the minimal tuple; in particular,
   * minhdr.t_data points MINIMAL_TUPLE_OFFSET bytes before mintuple.  This
   * allows column extraction to treat the case identically to regular
   * physical tuples.
   */
#define FIELDNO_MINIMALTUPLETABLESLOT_TUPLE 1
  HeapTuple tuple;      /* tuple wrapper */
  MinimalTuple mintuple;    /* minimal tuple, or NULL if none */
  HeapTupleData minhdr;   /* workspace for minimal-tuple-only case */
#define FIELDNO_MINIMALTUPLETABLESLOT_OFF 4
  uint32    off;      /* saved state for slot_deform_heap_tuple */
} MinimalTupleTableSlot;

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

/* in executor/execTuples.c */
extern TupleTableSlot *MakeTupleTableSlot(TupleDesc tupleDesc,
                      const TupleTableSlotOps *tts_ops,
                      uint16 flags);
extern TupleTableSlot *ExecAllocTableSlot(List **tupleTable, TupleDesc desc,
                      const TupleTableSlotOps *tts_ops,
                      uint16 flags);
extern void ExecResetTupleTable(List *tupleTable, bool shouldFree);
extern TupleTableSlot *MakeSingleTupleTableSlot(TupleDesc tupdesc,
                        const TupleTableSlotOps *tts_ops);
extern void ExecDropSingleTupleTableSlot(TupleTableSlot *slot);
extern void ExecSetSlotDescriptor(TupleTableSlot *slot, TupleDesc tupdesc);
extern TupleTableSlot *ExecStoreHeapTuple(HeapTuple tuple,
                      TupleTableSlot *slot,
                      bool shouldFree);
extern void ExecForceStoreHeapTuple(HeapTuple tuple,
                  TupleTableSlot *slot,
                  bool shouldFree);
extern TupleTableSlot *ExecStoreBufferHeapTuple(HeapTuple tuple,
                        TupleTableSlot *slot,
                        Buffer buffer);
extern TupleTableSlot *ExecStorePinnedBufferHeapTuple(HeapTuple tuple,
                            TupleTableSlot *slot,
                            Buffer buffer);
extern TupleTableSlot *ExecStoreMinimalTuple(MinimalTuple mtup,
                       TupleTableSlot *slot,
                       bool shouldFree);
extern void ExecForceStoreMinimalTuple(MinimalTuple mtup, TupleTableSlot *slot,
                     bool shouldFree);
extern TupleTableSlot *ExecStoreVirtualTuple(TupleTableSlot *slot);
extern TupleTableSlot *ExecStoreAllNullTuple(TupleTableSlot *slot);
extern void ExecStoreHeapTupleDatum(Datum data, TupleTableSlot *slot);
extern HeapTuple ExecFetchSlotHeapTuple(TupleTableSlot *slot, bool materialize, bool *shouldFree);
extern MinimalTuple ExecFetchSlotMinimalTuple(TupleTableSlot *slot,
                        bool *shouldFree);
extern Datum ExecFetchSlotHeapTupleDatum(TupleTableSlot *slot);
extern void slot_getmissingattrs(TupleTableSlot *slot, int startAttNum,
                 int lastAttNum);
extern void slot_getsomeattrs_int(TupleTableSlot *slot, int attnum);


#ifndef FRONTEND

/*
 * This function forces the entries of the slot's Datum/isnull arrays to be
 * valid at least up through the attnum'th entry.
 */
static inline void
slot_getsomeattrs(TupleTableSlot *slot, int attnum)
{
  /* Populate slot with attributes up to 'attnum', if it's not already */
  if (slot->tts_nvalid < attnum)
    slot->tts_ops->getsomeattrs(slot, attnum);
}

/*
 * slot_getallattrs
 *    This function forces all the entries of the slot's Datum/isnull
 *    arrays to be valid.  The caller may then extract data directly
 *    from those arrays instead of using slot_getattr.
 */
static inline void
slot_getallattrs(TupleTableSlot *slot)
{
  slot_getsomeattrs(slot, slot->tts_tupleDescriptor->natts);
}


/*
 * slot_attisnull
 *
 * Detect whether an attribute of the slot is null, without actually fetching
 * it.
 */
static inline bool
slot_attisnull(TupleTableSlot *slot, int attnum)
{
  Assert(attnum > 0);

  if (attnum > slot->tts_nvalid)
    slot_getsomeattrs(slot, attnum);

  return slot->tts_isnull[attnum - 1];
}

/*
 * slot_getattr - fetch one attribute of the slot's contents.
 */
static inline Datum
slot_getattr(TupleTableSlot *slot, int attnum,
       bool *isnull)
{
  Assert(attnum > 0);

  if (attnum > slot->tts_nvalid)
    slot_getsomeattrs(slot, attnum);

  *isnull = slot->tts_isnull[attnum - 1];

  return slot->tts_values[attnum - 1];
}

/*
 * slot_getsysattr - fetch a system attribute of the slot's current tuple.
 *
 *  If the slot type does not contain system attributes, this will throw an
 *  error.  Hence before calling this function, callers should make sure that
 *  the slot type is the one that supports system attributes.
 */
static inline Datum
slot_getsysattr(TupleTableSlot *slot, int attnum, bool *isnull)
{
  Assert(attnum < 0);     /* caller error */

  if (attnum == TableOidAttributeNumber)
  {
    *isnull = false;
    return ObjectIdGetDatum(slot->tts_tableOid);
  }
  else if (attnum == SelfItemPointerAttributeNumber)
  {
    *isnull = false;
    return PointerGetDatum(&slot->tts_tid);
  }

  /* Fetch the system attribute from the underlying tuple. */
  return slot->tts_ops->getsysattr(slot, attnum, isnull);
}

/*
 * slot_is_current_xact_tuple - check if the slot's current tuple is created
 *                by the current transaction.
 *
 *  If the slot does not contain a storage tuple, this will throw an error.
 *  Hence before calling this function, callers should make sure that the
 *  slot type supports storage tuples and that there is currently one inside
 *  the slot.
 */
static inline bool
slot_is_current_xact_tuple(TupleTableSlot *slot)
{
  return slot->tts_ops->is_current_xact_tuple(slot);
}

/*
 * ExecClearTuple - clear the slot's contents
 */
static inline TupleTableSlot *
ExecClearTuple(TupleTableSlot *slot)
{
  slot->tts_ops->clear(slot);

  return slot;
}

/*
 * ExecMaterializeSlot - force a slot into the "materialized" state.
 *
 * This causes the slot's tuple to be a local copy not dependent on any
 * external storage (i.e. pointing into a Buffer, or having allocations in
 * another memory context).
 *
 * A typical use for this operation is to prepare a computed tuple for being
 * stored on disk.  The original data may or may not be virtual, but in any
 * case we need a private copy for heap_insert to scribble on.
 */
static inline void
ExecMaterializeSlot(TupleTableSlot *slot)
{
  slot->tts_ops->materialize(slot);
}

/*
 * ExecCopySlotHeapTuple - return HeapTuple allocated in caller's context
 */
static inline HeapTuple
ExecCopySlotHeapTuple(TupleTableSlot *slot)
{
  Assert(!TTS_EMPTY(slot));

  return slot->tts_ops->copy_heap_tuple(slot);
}

/*
 * ExecCopySlotMinimalTuple - return MinimalTuple allocated in caller's context
 */
static inline MinimalTuple
ExecCopySlotMinimalTuple(TupleTableSlot *slot)
{
  return slot->tts_ops->copy_minimal_tuple(slot, 0);
}

/*
 * ExecCopySlotMinimalTupleExtra - return MinimalTuple allocated in caller's
 * context, with extra bytes (maxaligned and zeroed) before the tuple for data
 * the caller wishes to store along with the tuple (without requiring the
 * caller to make an additional allocation).
 */
static inline MinimalTuple
ExecCopySlotMinimalTupleExtra(TupleTableSlot *slot, Size extra)
{
  return slot->tts_ops->copy_minimal_tuple(slot, extra);
}

/*
 * ExecCopySlot - copy one slot's contents into another.
 *
 * If a source's system attributes are supposed to be accessed in the target
 * slot, the target slot and source slot types need to match.
 *
 * Currently, 'dstslot' and 'srcslot' must have the same number of attributes.
 * Future work could see this relaxed to allow the source to contain
 * additional attributes and have the code here only copy over the leading
 * attributes.
 */
static inline TupleTableSlot *
ExecCopySlot(TupleTableSlot *dstslot, TupleTableSlot *srcslot)
{
  Assert(!TTS_EMPTY(srcslot));
  Assert(srcslot != dstslot);
  Assert(dstslot->tts_tupleDescriptor->natts ==
       srcslot->tts_tupleDescriptor->natts);

  dstslot->tts_ops->copyslot(dstslot, srcslot);

  return dstslot;
}

#endif              /* FRONTEND */

#endif              /* TUPTABLE_H */

Coverage Report

Created: 2026-08-14 06:37

Line	Count	Source
1		/*-------------------------------------------------------------------------
2		*
3		* tuptable.h
4		* tuple table support stuff
5		*
6		*
7		* Portions Copyright (c) 1996-2026, PostgreSQL Global Development Group
8		* Portions Copyright (c) 1994, Regents of the University of California
9		*
10		* src/include/executor/tuptable.h
11		*
12		*-------------------------------------------------------------------------
13		*/
14		#ifndef TUPTABLE_H
15		#define TUPTABLE_H
16
17		#include "access/htup.h"
18		#include "access/sysattr.h"
19		#include "access/tupdesc.h"
20		#include "storage/buf.h"
21
22		/*----------
23		* The executor stores tuples in a "tuple table" which is a List of
24		* independent TupleTableSlots.
25		*
26		* There's various different types of tuple table slots, each being able to
27		* store different types of tuples. Additional types of slots can be added
28		* without modifying core code. The type of a slot is determined by the
29		* TupleTableSlotOps* passed to the slot creation routine. The builtin types
30		* of slots are
31		*
32		* 1. physical tuple in a disk buffer page (TTSOpsBufferHeapTuple)
33		* 2. physical tuple constructed in palloc'ed memory (TTSOpsHeapTuple)
34		* 3. "minimal" physical tuple constructed in palloc'ed memory
35		* (TTSOpsMinimalTuple)
36		* 4. "virtual" tuple consisting of Datum/isnull arrays (TTSOpsVirtual)
37		*
38		*
39		* The first two cases are similar in that they both deal with "materialized"