1 /*-------------------------------------------------------------------------
4 * tuple table support stuff
7 * Portions Copyright (c) 1996-2022, PostgreSQL Global Development Group
8 * Portions Copyright (c) 1994, Regents of the University of California
10 * src/include/executor/tuptable.h
12 *-------------------------------------------------------------------------
17 #include "access/htup.h"
18 #include "access/htup_details.h"
19 #include "access/sysattr.h"
20 #include "access/tupdesc.h"
21 #include "storage/buf.h"
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".
49 * (Actually, it could have an OID, but we have no need to access the OID.)
51 * A "virtual" tuple is an optimization used to minimize physical data copying
52 * in a nest of plan nodes. Until materialized pass-by-reference Datums in
53 * the slot point to storage that is not directly associated with the
54 * TupleTableSlot; generally they will point to part of a tuple stored in a
55 * lower plan node's output TupleTableSlot, or to a function result
56 * constructed in a plan node's per-tuple econtext. It is the responsibility
57 * of the generating plan node to be sure these resources are not released for
58 * as long as the virtual tuple needs to be valid or is materialized. Note
59 * also that a virtual tuple does not have any "system columns".
61 * The Datum/isnull arrays of a TupleTableSlot serve double duty. For virtual
62 * slots they are the authoritative data. For the other builtin slots,
63 * the arrays contain data extracted from the tuple. (In this state, any
64 * pass-by-reference Datums point into the physical tuple.) The extracted
65 * information is built "lazily", ie, only as needed. This serves to avoid
66 * repeated extraction of data from the physical tuple.
68 * A TupleTableSlot can also be "empty", indicated by flag TTS_FLAG_EMPTY set
69 * in tts_flags, holding no valid data. This is the only valid state for a
70 * freshly-created slot that has not yet had a tuple descriptor assigned to
71 * it. In this state, TTS_SHOULDFREE should not be set in tts_flags, tts_tuple
72 * must be NULL and tts_nvalid zero.
74 * The tupleDescriptor is simply referenced, not copied, by the TupleTableSlot
75 * code. The caller of ExecSetSlotDescriptor() is responsible for providing
76 * a descriptor that will live as long as the slot does. (Typically, both
77 * slots and descriptors are in per-query memory and are freed by memory
78 * context deallocation at query end; so it's not worth providing any extra
79 * mechanism to do more. However, the slot will increment the tupdesc
80 * reference count if a reference-counted tupdesc is supplied.)
82 * When TTS_SHOULDFREE is set in tts_flags, the physical tuple is "owned" by
83 * the slot and should be freed when the slot's reference to the tuple is
86 * tts_values/tts_isnull are allocated either when the slot is created (when
87 * the descriptor is provided), or when a descriptor is assigned to the slot;
88 * they are of length equal to the descriptor's natts.
90 * The TTS_FLAG_SLOW flag is saved state for
91 * slot_deform_heap_tuple, and should not be touched by any other code.
95 /* true = slot is empty */
96 #define TTS_FLAG_EMPTY (1 << 1)
97 #define TTS_EMPTY(slot) (((slot)->tts_flags & TTS_FLAG_EMPTY) != 0)
99 /* should pfree tuple "owned" by the slot? */
100 #define TTS_FLAG_SHOULDFREE (1 << 2)
101 #define TTS_SHOULDFREE(slot) (((slot)->tts_flags & TTS_FLAG_SHOULDFREE) != 0)
103 /* saved state for slot_deform_heap_tuple */
104 #define TTS_FLAG_SLOW (1 << 3)
105 #define TTS_SLOW(slot) (((slot)->tts_flags & TTS_FLAG_SLOW) != 0)
107 /* fixed tuple descriptor */
108 #define TTS_FLAG_FIXED (1 << 4)
109 #define TTS_FIXED(slot) (((slot)->tts_flags & TTS_FLAG_FIXED) != 0)
111 struct TupleTableSlotOps
;
112 typedef struct TupleTableSlotOps TupleTableSlotOps
;
114 /* base tuple table slot type */
115 typedef struct TupleTableSlot
118 #define FIELDNO_TUPLETABLESLOT_FLAGS 1
119 uint16 tts_flags
; /* Boolean states */
120 #define FIELDNO_TUPLETABLESLOT_NVALID 2
121 AttrNumber tts_nvalid
; /* # of valid values in tts_values */
122 const TupleTableSlotOps
*const tts_ops
; /* implementation of slot */
123 #define FIELDNO_TUPLETABLESLOT_TUPLEDESCRIPTOR 4
124 TupleDesc tts_tupleDescriptor
; /* slot's tuple descriptor */
125 #define FIELDNO_TUPLETABLESLOT_VALUES 5
126 Datum
*tts_values
; /* current per-attribute values */
127 #define FIELDNO_TUPLETABLESLOT_ISNULL 6
128 bool *tts_isnull
; /* current per-attribute isnull flags */
129 MemoryContext tts_mcxt
; /* slot itself is in this context */
130 ItemPointerData tts_tid
; /* stored tuple's tid */
131 Oid tts_tableOid
; /* table oid of tuple */
134 /* routines for a TupleTableSlot implementation */
135 struct TupleTableSlotOps
137 /* Minimum size of the slot */
138 size_t base_slot_size
;
140 /* Initialization. */
141 void (*init
) (TupleTableSlot
*slot
);
144 void (*release
) (TupleTableSlot
*slot
);
147 * Clear the contents of the slot. Only the contents are expected to be
148 * cleared and not the tuple descriptor. Typically an implementation of
149 * this callback should free the memory allocated for the tuple contained
152 void (*clear
) (TupleTableSlot
*slot
);
155 * Fill up first natts entries of tts_values and tts_isnull arrays with
156 * values from the tuple contained in the slot. The function may be called
157 * with natts more than the number of attributes available in the tuple,
158 * in which case it should set tts_nvalid to the number of returned
161 void (*getsomeattrs
) (TupleTableSlot
*slot
, int natts
);
164 * Returns value of the given system attribute as a datum and sets isnull
165 * to false, if it's not NULL. Throws an error if the slot type does not
166 * support system attributes.
168 Datum (*getsysattr
) (TupleTableSlot
*slot
, int attnum
, bool *isnull
);
171 * Make the contents of the slot solely depend on the slot, and not on
172 * underlying resources (like another memory context, buffers, etc).
174 void (*materialize
) (TupleTableSlot
*slot
);
177 * Copy the contents of the source slot into the destination slot's own
178 * context. Invoked using callback of the destination slot.
180 void (*copyslot
) (TupleTableSlot
*dstslot
, TupleTableSlot
*srcslot
);
183 * Return a heap tuple "owned" by the slot. It is slot's responsibility to
184 * free the memory consumed by the heap tuple. If the slot can not "own" a
185 * heap tuple, it should not implement this callback and should set it as
188 HeapTuple (*get_heap_tuple
) (TupleTableSlot
*slot
);
191 * Return a minimal tuple "owned" by the slot. It is slot's responsibility
192 * to free the memory consumed by the minimal tuple. If the slot can not
193 * "own" a minimal tuple, it should not implement this callback and should
196 MinimalTuple (*get_minimal_tuple
) (TupleTableSlot
*slot
);
199 * Return a copy of heap tuple representing the contents of the slot. The
200 * copy needs to be palloc'd in the current memory context. The slot
201 * itself is expected to remain unaffected. It is *not* expected to have
202 * meaningful "system columns" in the copy. The copy is not be "owned" by
203 * the slot i.e. the caller has to take responsibility to free memory
204 * consumed by the slot.
206 HeapTuple (*copy_heap_tuple
) (TupleTableSlot
*slot
);
209 * Return a copy of minimal tuple representing the contents of the slot.
210 * The copy needs to be palloc'd in the current memory context. The slot
211 * itself is expected to remain unaffected. It is *not* expected to have
212 * meaningful "system columns" in the copy. The copy is not be "owned" by
213 * the slot i.e. the caller has to take responsibility to free memory
214 * consumed by the slot.
216 MinimalTuple (*copy_minimal_tuple
) (TupleTableSlot
*slot
);
220 * Predefined TupleTableSlotOps for various types of TupleTableSlotOps. The
221 * same are used to identify the type of a given slot.
223 extern PGDLLIMPORT
const TupleTableSlotOps TTSOpsVirtual
;
224 extern PGDLLIMPORT
const TupleTableSlotOps TTSOpsHeapTuple
;
225 extern PGDLLIMPORT
const TupleTableSlotOps TTSOpsMinimalTuple
;
226 extern PGDLLIMPORT
const TupleTableSlotOps TTSOpsBufferHeapTuple
;
228 #define TTS_IS_VIRTUAL(slot) ((slot)->tts_ops == &TTSOpsVirtual)
229 #define TTS_IS_HEAPTUPLE(slot) ((slot)->tts_ops == &TTSOpsHeapTuple)
230 #define TTS_IS_MINIMALTUPLE(slot) ((slot)->tts_ops == &TTSOpsMinimalTuple)
231 #define TTS_IS_BUFFERTUPLE(slot) ((slot)->tts_ops == &TTSOpsBufferHeapTuple)
235 * Tuple table slot implementations.
238 typedef struct VirtualTupleTableSlot
242 char *data
; /* data for materialized slots */
243 } VirtualTupleTableSlot
;
245 typedef struct HeapTupleTableSlot
249 #define FIELDNO_HEAPTUPLETABLESLOT_TUPLE 1
250 HeapTuple tuple
; /* physical tuple */
251 #define FIELDNO_HEAPTUPLETABLESLOT_OFF 2
252 uint32 off
; /* saved state for slot_deform_heap_tuple */
253 HeapTupleData tupdata
; /* optional workspace for storing tuple */
254 } HeapTupleTableSlot
;
256 /* heap tuple residing in a buffer */
257 typedef struct BufferHeapTupleTableSlot
259 HeapTupleTableSlot base
;
262 * If buffer is not InvalidBuffer, then the slot is holding a pin on the
263 * indicated buffer page; drop the pin when we release the slot's
264 * reference to that buffer. (TTS_FLAG_SHOULDFREE should not be set in
265 * such a case, since presumably tts_tuple is pointing into the buffer.)
267 Buffer buffer
; /* tuple's buffer, or InvalidBuffer */
268 } BufferHeapTupleTableSlot
;
270 typedef struct MinimalTupleTableSlot
275 * In a minimal slot tuple points at minhdr and the fields of that struct
276 * are set correctly for access to the minimal tuple; in particular,
277 * minhdr.t_data points MINIMAL_TUPLE_OFFSET bytes before mintuple. This
278 * allows column extraction to treat the case identically to regular
281 #define FIELDNO_MINIMALTUPLETABLESLOT_TUPLE 1
282 HeapTuple tuple
; /* tuple wrapper */
283 MinimalTuple mintuple
; /* minimal tuple, or NULL if none */
284 HeapTupleData minhdr
; /* workspace for minimal-tuple-only case */
285 #define FIELDNO_MINIMALTUPLETABLESLOT_OFF 4
286 uint32 off
; /* saved state for slot_deform_heap_tuple */
287 } MinimalTupleTableSlot
;
290 * TupIsNull -- is a TupleTableSlot empty?
292 #define TupIsNull(slot) \
293 ((slot) == NULL || TTS_EMPTY(slot))
295 /* in executor/execTuples.c */
296 extern TupleTableSlot
*MakeTupleTableSlot(TupleDesc tupleDesc
,
297 const TupleTableSlotOps
*tts_ops
);
298 extern TupleTableSlot
*ExecAllocTableSlot(List
**tupleTable
, TupleDesc desc
,
299 const TupleTableSlotOps
*tts_ops
);
300 extern void ExecResetTupleTable(List
*tupleTable
, bool shouldFree
);
301 extern TupleTableSlot
*MakeSingleTupleTableSlot(TupleDesc tupdesc
,
302 const TupleTableSlotOps
*tts_ops
);
303 extern void ExecDropSingleTupleTableSlot(TupleTableSlot
*slot
);
304 extern void ExecSetSlotDescriptor(TupleTableSlot
*slot
, TupleDesc tupdesc
);
305 extern TupleTableSlot
*ExecStoreHeapTuple(HeapTuple tuple
,
306 TupleTableSlot
*slot
,
308 extern void ExecForceStoreHeapTuple(HeapTuple tuple
,
309 TupleTableSlot
*slot
,
311 extern TupleTableSlot
*ExecStoreBufferHeapTuple(HeapTuple tuple
,
312 TupleTableSlot
*slot
,
314 extern TupleTableSlot
*ExecStorePinnedBufferHeapTuple(HeapTuple tuple
,
315 TupleTableSlot
*slot
,
317 extern TupleTableSlot
*ExecStoreMinimalTuple(MinimalTuple mtup
,
318 TupleTableSlot
*slot
,
320 extern void ExecForceStoreMinimalTuple(MinimalTuple mtup
, TupleTableSlot
*slot
,
322 extern TupleTableSlot
*ExecStoreVirtualTuple(TupleTableSlot
*slot
);
323 extern TupleTableSlot
*ExecStoreAllNullTuple(TupleTableSlot
*slot
);
324 extern void ExecStoreHeapTupleDatum(Datum data
, TupleTableSlot
*slot
);
325 extern HeapTuple
ExecFetchSlotHeapTuple(TupleTableSlot
*slot
, bool materialize
, bool *shouldFree
);
326 extern MinimalTuple
ExecFetchSlotMinimalTuple(TupleTableSlot
*slot
,
328 extern Datum
ExecFetchSlotHeapTupleDatum(TupleTableSlot
*slot
);
329 extern void slot_getmissingattrs(TupleTableSlot
*slot
, int startAttNum
,
331 extern void slot_getsomeattrs_int(TupleTableSlot
*slot
, int attnum
);
337 * This function forces the entries of the slot's Datum/isnull arrays to be
338 * valid at least up through the attnum'th entry.
341 slot_getsomeattrs(TupleTableSlot
*slot
, int attnum
)
343 if (slot
->tts_nvalid
< attnum
)
344 slot_getsomeattrs_int(slot
, attnum
);
349 * This function forces all the entries of the slot's Datum/isnull
350 * arrays to be valid. The caller may then extract data directly
351 * from those arrays instead of using slot_getattr.
354 slot_getallattrs(TupleTableSlot
*slot
)
356 slot_getsomeattrs(slot
, slot
->tts_tupleDescriptor
->natts
);
363 * Detect whether an attribute of the slot is null, without actually fetching
367 slot_attisnull(TupleTableSlot
*slot
, int attnum
)
369 AssertArg(attnum
> 0);
371 if (attnum
> slot
->tts_nvalid
)
372 slot_getsomeattrs(slot
, attnum
);
374 return slot
->tts_isnull
[attnum
- 1];
378 * slot_getattr - fetch one attribute of the slot's contents.
381 slot_getattr(TupleTableSlot
*slot
, int attnum
,
384 AssertArg(attnum
> 0);
386 if (attnum
> slot
->tts_nvalid
)
387 slot_getsomeattrs(slot
, attnum
);
389 *isnull
= slot
->tts_isnull
[attnum
- 1];
391 return slot
->tts_values
[attnum
- 1];
395 * slot_getsysattr - fetch a system attribute of the slot's current tuple.
397 * If the slot type does not contain system attributes, this will throw an
398 * error. Hence before calling this function, callers should make sure that
399 * the slot type is the one that supports system attributes.
402 slot_getsysattr(TupleTableSlot
*slot
, int attnum
, bool *isnull
)
404 AssertArg(attnum
< 0); /* caller error */
406 if (attnum
== TableOidAttributeNumber
)
409 return ObjectIdGetDatum(slot
->tts_tableOid
);
411 else if (attnum
== SelfItemPointerAttributeNumber
)
414 return PointerGetDatum(&slot
->tts_tid
);
417 /* Fetch the system attribute from the underlying tuple. */
418 return slot
->tts_ops
->getsysattr(slot
, attnum
, isnull
);
422 * ExecClearTuple - clear the slot's contents
424 static inline TupleTableSlot
*
425 ExecClearTuple(TupleTableSlot
*slot
)
427 slot
->tts_ops
->clear(slot
);
432 /* ExecMaterializeSlot - force a slot into the "materialized" state.
434 * This causes the slot's tuple to be a local copy not dependent on any
435 * external storage (i.e. pointing into a Buffer, or having allocations in
436 * another memory context).
438 * A typical use for this operation is to prepare a computed tuple for being
439 * stored on disk. The original data may or may not be virtual, but in any
440 * case we need a private copy for heap_insert to scribble on.
443 ExecMaterializeSlot(TupleTableSlot
*slot
)
445 slot
->tts_ops
->materialize(slot
);
449 * ExecCopySlotHeapTuple - return HeapTuple allocated in caller's context
451 static inline HeapTuple
452 ExecCopySlotHeapTuple(TupleTableSlot
*slot
)
454 Assert(!TTS_EMPTY(slot
));
456 return slot
->tts_ops
->copy_heap_tuple(slot
);
460 * ExecCopySlotMinimalTuple - return MinimalTuple allocated in caller's context
462 static inline MinimalTuple
463 ExecCopySlotMinimalTuple(TupleTableSlot
*slot
)
465 return slot
->tts_ops
->copy_minimal_tuple(slot
);
469 * ExecCopySlot - copy one slot's contents into another.
471 * If a source's system attributes are supposed to be accessed in the target
472 * slot, the target slot and source slot types need to match.
474 static inline TupleTableSlot
*
475 ExecCopySlot(TupleTableSlot
*dstslot
, TupleTableSlot
*srcslot
)
477 Assert(!TTS_EMPTY(srcslot
));
478 AssertArg(srcslot
!= dstslot
);
480 dstslot
->tts_ops
->copyslot(dstslot
, srcslot
);
485 #endif /* FRONTEND */
487 #endif /* TUPTABLE_H */