1/*-------------------------------------------------------------------------
4 * tuple table support stuff
7 * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
8 * Portions Copyright (c) 1994, Regents of the University of California
10 * src/include/executor/tuptable.h
12 *-------------------------------------------------------------------------
24 * The executor stores tuples in a "tuple table" which is a List of
25 * independent TupleTableSlots.
27 * There's various different types of tuple table slots, each being able to
28 * store different types of tuples. Additional types of slots can be added
29 * without modifying core code. The type of a slot is determined by the
30 * TupleTableSlotOps* passed to the slot creation routine. The builtin types
33 * 1. physical tuple in a disk buffer page (TTSOpsBufferHeapTuple)
34 * 2. physical tuple constructed in palloc'ed memory (TTSOpsHeapTuple)
35 * 3. "minimal" physical tuple constructed in palloc'ed memory
36 * (TTSOpsMinimalTuple)
37 * 4. "virtual" tuple consisting of Datum/isnull arrays (TTSOpsVirtual)
40 * The first two cases are similar in that they both deal with "materialized"
41 * tuples, but resource management is different. For a tuple in a disk page
42 * we need to hold a pin on the buffer until the TupleTableSlot's reference
43 * to the tuple is dropped; while for a palloc'd tuple we usually want the
44 * tuple pfree'd when the TupleTableSlot's reference is dropped.
46 * A "minimal" tuple is handled similarly to a palloc'd regular tuple.
47 * At present, minimal tuples never are stored in buffers, so there is no
48 * parallel to case 1. Note that a minimal tuple has no "system columns".
50 * A "virtual" tuple is an optimization used to minimize physical data copying
51 * in a nest of plan nodes. Until materialized pass-by-reference Datums in
52 * the slot point to storage that is not directly associated with the
53 * TupleTableSlot; generally they will point to part of a tuple stored in a
54 * lower plan node's output TupleTableSlot, or to a function result
55 * constructed in a plan node's per-tuple econtext. It is the responsibility
56 * of the generating plan node to be sure these resources are not released for
57 * as long as the virtual tuple needs to be valid or is materialized. Note
58 * also that a virtual tuple does not have any "system columns".
60 * The Datum/isnull arrays of a TupleTableSlot serve double duty. For virtual
61 * slots they are the authoritative data. For the other builtin slots,
62 * the arrays contain data extracted from the tuple. (In this state, any
63 * pass-by-reference Datums point into the physical tuple.) The extracted
64 * information is built "lazily", ie, only as needed. This serves to avoid
65 * repeated extraction of data from the physical tuple.
67 * A TupleTableSlot can also be "empty", indicated by flag TTS_FLAG_EMPTY set
68 * in tts_flags, holding no valid data. This is the only valid state for a
69 * freshly-created slot that has not yet had a tuple descriptor assigned to
70 * it. In this state, TTS_FLAG_SHOULDFREE should not be set in tts_flags and
71 * tts_nvalid should be set to zero.
73 * The tupleDescriptor is simply referenced, not copied, by the TupleTableSlot
74 * code. The caller of ExecSetSlotDescriptor() is responsible for providing
75 * a descriptor that will live as long as the slot does. (Typically, both
76 * slots and descriptors are in per-query memory and are freed by memory
77 * context deallocation at query end; so it's not worth providing any extra
78 * mechanism to do more. However, the slot will increment the tupdesc
79 * reference count if a reference-counted tupdesc is supplied.)
81 * When TTS_FLAG_SHOULDFREE is set in tts_flags, the physical tuple is "owned"
82 * by the slot and should be freed when the slot's reference to the tuple is
85 * tts_values/tts_isnull are allocated either when the slot is created (when
86 * the descriptor is provided), or when a descriptor is assigned to the slot;
87 * they are of length equal to the descriptor's natts.
89 * The TTS_FLAG_SLOW flag is saved state for
90 * slot_deform_heap_tuple, and should not be touched by any other code.
94/* true = slot is empty */
95 #define TTS_FLAG_EMPTY (1 << 1)
96 #define TTS_EMPTY(slot) (((slot)->tts_flags & TTS_FLAG_EMPTY) != 0)
98/* should pfree tuple "owned" by the slot? */
99 #define TTS_FLAG_SHOULDFREE (1 << 2)
100 #define TTS_SHOULDFREE(slot) (((slot)->tts_flags & TTS_FLAG_SHOULDFREE) != 0)
102/* saved state for slot_deform_heap_tuple */
103 #define TTS_FLAG_SLOW (1 << 3)
104 #define TTS_SLOW(slot) (((slot)->tts_flags & TTS_FLAG_SLOW) != 0)
106/* fixed tuple descriptor */
107 #define TTS_FLAG_FIXED (1 << 4)
108 #define TTS_FIXED(slot) (((slot)->tts_flags & TTS_FLAG_FIXED) != 0)
113/* base tuple table slot type */
117 #define FIELDNO_TUPLETABLESLOT_FLAGS 1
119 #define FIELDNO_TUPLETABLESLOT_NVALID 2
122 #define FIELDNO_TUPLETABLESLOT_TUPLEDESCRIPTOR 4
124 #define FIELDNO_TUPLETABLESLOT_VALUES 5
126 #define FIELDNO_TUPLETABLESLOT_ISNULL 6
133/* routines for a TupleTableSlot implementation */
136 /* Minimum size of the slot */
139 /* Initialization. */
146 * Clear the contents of the slot. Only the contents are expected to be
147 * cleared and not the tuple descriptor. Typically an implementation of
148 * this callback should free the memory allocated for the tuple contained
154 * Fill up first natts entries of tts_values and tts_isnull arrays with
155 * values from the tuple contained in the slot. The function may be called
156 * with natts more than the number of attributes available in the tuple,
157 * in which case it should set tts_nvalid to the number of returned
163 * Returns value of the given system attribute as a datum and sets isnull
164 * to false, if it's not NULL. Throws an error if the slot type does not
165 * support system attributes.
170 * Check if the tuple is created by the current transaction. Throws an
171 * error if the slot doesn't contain the storage tuple.
176 * Make the contents of the slot solely depend on the slot, and not on
177 * underlying resources (like another memory context, buffers, etc).
182 * Copy the contents of the source slot into the destination slot's own
183 * context. Invoked using callback of the destination slot. 'dstslot' and
184 * 'srcslot' can be assumed to have the same number of attributes.
189 * Return a heap tuple "owned" by the slot. It is slot's responsibility to
190 * free the memory consumed by the heap tuple. If the slot can not "own" a
191 * heap tuple, it should not implement this callback and should set it as
197 * Return a minimal tuple "owned" by the slot. It is slot's responsibility
198 * to free the memory consumed by the minimal tuple. If the slot can not
199 * "own" a minimal tuple, it should not implement this callback and should
205 * Return a copy of heap tuple representing the contents of the slot. The
206 * copy needs to be palloc'd in the current memory context. The slot
207 * itself is expected to remain unaffected. It is *not* expected to have
208 * meaningful "system columns" in the copy. The copy is not be "owned" by
209 * the slot i.e. the caller has to take responsibility to free memory
210 * consumed by the slot.
215 * Return a copy of minimal tuple representing the contents of the slot.
216 * The copy needs to be palloc'd in the current memory context. The slot
217 * itself is expected to remain unaffected. It is *not* expected to have
218 * meaningful "system columns" in the copy. The copy is not be "owned" by
219 * the slot i.e. the caller has to take responsibility to free memory
220 * consumed by the slot.
222 * The copy has "extra" bytes (maxaligned and zeroed) available before the
223 * tuple, which is useful so that some callers may store extra data along
224 * with the minimal tuple without the need for an additional allocation.
230 * Predefined TupleTableSlotOps for various types of TupleTableSlotOps. The
231 * same are used to identify the type of a given slot.
238 #define TTS_IS_VIRTUAL(slot) ((slot)->tts_ops == &TTSOpsVirtual)
239 #define TTS_IS_HEAPTUPLE(slot) ((slot)->tts_ops == &TTSOpsHeapTuple)
240 #define TTS_IS_MINIMALTUPLE(slot) ((slot)->tts_ops == &TTSOpsMinimalTuple)
241 #define TTS_IS_BUFFERTUPLE(slot) ((slot)->tts_ops == &TTSOpsBufferHeapTuple)
245 * Tuple table slot implementations.
254 char *
data;
/* data for materialized slots */
263 #define FIELDNO_HEAPTUPLETABLESLOT_TUPLE 1
265 #define FIELDNO_HEAPTUPLETABLESLOT_OFF 2
266 uint32 off;
/* saved state for slot_deform_heap_tuple */
270/* heap tuple residing in a buffer */
278 * If buffer is not InvalidBuffer, then the slot is holding a pin on the
279 * indicated buffer page; drop the pin when we release the slot's
280 * reference to that buffer. (TTS_FLAG_SHOULDFREE should not be set in
281 * such a case, since presumably base.tuple is pointing into the buffer.)
293 * In a minimal slot tuple points at minhdr and the fields of that struct
294 * are set correctly for access to the minimal tuple; in particular,
295 * minhdr.t_data points MINIMAL_TUPLE_OFFSET bytes before mintuple. This
296 * allows column extraction to treat the case identically to regular
299 #define FIELDNO_MINIMALTUPLETABLESLOT_TUPLE 1
303 #define FIELDNO_MINIMALTUPLETABLESLOT_OFF 4
304 uint32 off;
/* saved state for slot_deform_heap_tuple */
308 * TupIsNull -- is a TupleTableSlot empty?
310 #define TupIsNull(slot) \
311 ((slot) == NULL || TTS_EMPTY(slot))
313/* in executor/execTuples.c */
355 * This function forces the entries of the slot's Datum/isnull arrays to be
356 * valid at least up through the attnum'th entry.
367 * This function forces all the entries of the slot's Datum/isnull
368 * arrays to be valid. The caller may then extract data directly
369 * from those arrays instead of using slot_getattr.
381 * Detect whether an attribute of the slot is null, without actually fetching
396 * slot_getattr - fetch one attribute of the slot's contents.
413 * slot_getsysattr - fetch a system attribute of the slot's current tuple.
415 * If the slot type does not contain system attributes, this will throw an
416 * error. Hence before calling this function, callers should make sure that
417 * the slot type is the one that supports system attributes.
435 /* Fetch the system attribute from the underlying tuple. */
440 * slot_is_current_xact_tuple - check if the slot's current tuple is created
441 * by the current transaction.
443 * If the slot does not contain a storage tuple, this will throw an error.
444 * Hence before calling this function, callers should make sure that the
445 * slot type supports storage tuples and that there is currently one inside
455 * ExecClearTuple - clear the slot's contents
465/* ExecMaterializeSlot - force a slot into the "materialized" state.
467 * This causes the slot's tuple to be a local copy not dependent on any
468 * external storage (i.e. pointing into a Buffer, or having allocations in
469 * another memory context).
471 * A typical use for this operation is to prepare a computed tuple for being
472 * stored on disk. The original data may or may not be virtual, but in any
473 * case we need a private copy for heap_insert to scribble on.
482 * ExecCopySlotHeapTuple - return HeapTuple allocated in caller's context
493 * ExecCopySlotMinimalTuple - return MinimalTuple allocated in caller's context
502 * ExecCopySlotMinimalTupleExtra - return MinimalTuple allocated in caller's
503 * context, with extra bytes (maxaligned and zeroed) before the tuple for data
504 * the caller wishes to store along with the tuple (without requiring the
505 * caller to make an additional allocation).
514 * ExecCopySlot - copy one slot's contents into another.
516 * If a source's system attributes are supposed to be accessed in the target
517 * slot, the target slot and source slot types need to match.
519 * Currently, 'dstslot' and 'srcslot' must have the same number of attributes.
520 * Future work could see this relaxed to allow the source to contain
521 * additional attributes and have the code here only copy over the leading
528 Assert(srcslot != dstslot);
539#endif /* TUPTABLE_H */
Assert(PointerIsAligned(start, uint64))
HeapTupleData * HeapTuple
MinimalTupleData * MinimalTuple
static Datum PointerGetDatum(const void *X)
static Datum ObjectIdGetDatum(Oid X)
pg_node_attr(abstract) HeapTupleTableSlot base
pg_node_attr(abstract) TupleTableSlot base
pg_node_attr(abstract) TupleTableSlot base
Datum(* getsysattr)(TupleTableSlot *slot, int attnum, bool *isnull)
bool(* is_current_xact_tuple)(TupleTableSlot *slot)
HeapTuple(* get_heap_tuple)(TupleTableSlot *slot)
MinimalTuple(* copy_minimal_tuple)(TupleTableSlot *slot, Size extra)
void(* init)(TupleTableSlot *slot)
void(* copyslot)(TupleTableSlot *dstslot, TupleTableSlot *srcslot)
void(* getsomeattrs)(TupleTableSlot *slot, int natts)
HeapTuple(* copy_heap_tuple)(TupleTableSlot *slot)
MinimalTuple(* get_minimal_tuple)(TupleTableSlot *slot)
void(* clear)(TupleTableSlot *slot)
void(* materialize)(TupleTableSlot *slot)
void(* release)(TupleTableSlot *slot)
TupleDesc tts_tupleDescriptor
const TupleTableSlotOps *const tts_ops
pg_node_attr(abstract) TupleTableSlot base
#define TableOidAttributeNumber
#define SelfItemPointerAttributeNumber
PGDLLIMPORT const TupleTableSlotOps TTSOpsMinimalTuple
void ExecResetTupleTable(List *tupleTable, bool shouldFree)
struct TupleTableSlot TupleTableSlot
TupleTableSlot * ExecStorePinnedBufferHeapTuple(HeapTuple tuple, TupleTableSlot *slot, Buffer buffer)
TupleTableSlot * MakeSingleTupleTableSlot(TupleDesc tupdesc, const TupleTableSlotOps *tts_ops)
static MinimalTuple ExecCopySlotMinimalTuple(TupleTableSlot *slot)
void ExecDropSingleTupleTableSlot(TupleTableSlot *slot)
static void slot_getsomeattrs(TupleTableSlot *slot, int attnum)
TupleTableSlot * ExecStoreVirtualTuple(TupleTableSlot *slot)
struct MinimalTupleTableSlot MinimalTupleTableSlot
TupleTableSlot * ExecAllocTableSlot(List **tupleTable, TupleDesc desc, const TupleTableSlotOps *tts_ops)
void ExecForceStoreMinimalTuple(MinimalTuple mtup, TupleTableSlot *slot, bool shouldFree)
static HeapTuple ExecCopySlotHeapTuple(TupleTableSlot *slot)
MinimalTuple ExecFetchSlotMinimalTuple(TupleTableSlot *slot, bool *shouldFree)
static Datum slot_getsysattr(TupleTableSlot *slot, int attnum, bool *isnull)
TupleTableSlot * ExecStoreMinimalTuple(MinimalTuple mtup, TupleTableSlot *slot, bool shouldFree)
PGDLLIMPORT const TupleTableSlotOps TTSOpsVirtual
HeapTuple ExecFetchSlotHeapTuple(TupleTableSlot *slot, bool materialize, bool *shouldFree)
void slot_getmissingattrs(TupleTableSlot *slot, int startAttNum, int lastAttNum)
static Datum slot_getattr(TupleTableSlot *slot, int attnum, bool *isnull)
TupleTableSlot * ExecStoreBufferHeapTuple(HeapTuple tuple, TupleTableSlot *slot, Buffer buffer)
static bool slot_is_current_xact_tuple(TupleTableSlot *slot)
void ExecStoreHeapTupleDatum(Datum data, TupleTableSlot *slot)
void ExecSetSlotDescriptor(TupleTableSlot *slot, TupleDesc tupdesc)
static TupleTableSlot * ExecClearTuple(TupleTableSlot *slot)
static MinimalTuple ExecCopySlotMinimalTupleExtra(TupleTableSlot *slot, Size extra)
PGDLLIMPORT const TupleTableSlotOps TTSOpsHeapTuple
Datum ExecFetchSlotHeapTupleDatum(TupleTableSlot *slot)
static void slot_getallattrs(TupleTableSlot *slot)
void slot_getsomeattrs_int(TupleTableSlot *slot, int attnum)
struct HeapTupleTableSlot HeapTupleTableSlot
static TupleTableSlot * ExecCopySlot(TupleTableSlot *dstslot, TupleTableSlot *srcslot)
struct BufferHeapTupleTableSlot BufferHeapTupleTableSlot
PGDLLIMPORT const TupleTableSlotOps TTSOpsBufferHeapTuple
static void ExecMaterializeSlot(TupleTableSlot *slot)
TupleTableSlot * ExecStoreAllNullTuple(TupleTableSlot *slot)
TupleTableSlot * MakeTupleTableSlot(TupleDesc tupleDesc, const TupleTableSlotOps *tts_ops)
TupleTableSlot * ExecStoreHeapTuple(HeapTuple tuple, TupleTableSlot *slot, bool shouldFree)
static bool slot_attisnull(TupleTableSlot *slot, int attnum)
struct VirtualTupleTableSlot VirtualTupleTableSlot
void ExecForceStoreHeapTuple(HeapTuple tuple, TupleTableSlot *slot, bool shouldFree)