Line data Source code
1 : /*-------------------------------------------------------------------------
2 : *
3 : * tuptable.h
4 : * tuple table support stuff
5 : *
6 : *
7 : * Portions Copyright (c) 1996-2024, 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/htup_details.h"
19 : #include "access/sysattr.h"
20 : #include "access/tupdesc.h"
21 : #include "storage/buf.h"
22 :
23 : /*----------
24 : * The executor stores tuples in a "tuple table" which is a List of
25 : * independent TupleTableSlots.
26 : *
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
31 : * of slots are
32 : *
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)
38 : *
39 : *
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.
45 : *
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 : *
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".
59 : *
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.
66 : *
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.
72 : *
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.)
80 : *
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
83 : * dropped.
84 : *
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.
88 : *
89 : * The TTS_FLAG_SLOW flag is saved state for
90 : * slot_deform_heap_tuple, and should not be touched by any other code.
91 : *----------
92 : */
93 :
94 : /* true = slot is empty */
95 : #define TTS_FLAG_EMPTY (1 << 1)
96 : #define TTS_EMPTY(slot) (((slot)->tts_flags & TTS_FLAG_EMPTY) != 0)
97 :
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)
101 :
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)
105 :
106 : /* fixed tuple descriptor */
107 : #define TTS_FLAG_FIXED (1 << 4)
108 : #define TTS_FIXED(slot) (((slot)->tts_flags & TTS_FLAG_FIXED) != 0)
109 :
110 : struct TupleTableSlotOps;
111 : typedef struct TupleTableSlotOps TupleTableSlotOps;
112 :
113 : /* base tuple table slot type */
114 : typedef struct TupleTableSlot
115 : {
116 : NodeTag type;
117 : #define FIELDNO_TUPLETABLESLOT_FLAGS 1
118 : uint16 tts_flags; /* Boolean states */
119 : #define FIELDNO_TUPLETABLESLOT_NVALID 2
120 : AttrNumber tts_nvalid; /* # of valid values in tts_values */
121 : const TupleTableSlotOps *const tts_ops; /* implementation of slot */
122 : #define FIELDNO_TUPLETABLESLOT_TUPLEDESCRIPTOR 4
123 : TupleDesc tts_tupleDescriptor; /* slot's tuple descriptor */
124 : #define FIELDNO_TUPLETABLESLOT_VALUES 5
125 : Datum *tts_values; /* current per-attribute values */
126 : #define FIELDNO_TUPLETABLESLOT_ISNULL 6
127 : bool *tts_isnull; /* current per-attribute isnull flags */
128 : MemoryContext tts_mcxt; /* slot itself is in this context */
129 : ItemPointerData tts_tid; /* stored tuple's tid */
130 : Oid tts_tableOid; /* table oid of tuple */
131 : } TupleTableSlot;
132 :
133 : /* routines for a TupleTableSlot implementation */
134 : struct TupleTableSlotOps
135 : {
136 : /* Minimum size of the slot */
137 : size_t base_slot_size;
138 :
139 : /* Initialization. */
140 : void (*init) (TupleTableSlot *slot);
141 :
142 : /* Destruction. */
143 : void (*release) (TupleTableSlot *slot);
144 :
145 : /*
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
149 : * in the slot.
150 : */
151 : void (*clear) (TupleTableSlot *slot);
152 :
153 : /*
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
158 : * columns.
159 : */
160 : void (*getsomeattrs) (TupleTableSlot *slot, int natts);
161 :
162 : /*
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.
166 : */
167 : Datum (*getsysattr) (TupleTableSlot *slot, int attnum, bool *isnull);
168 :
169 : /*
170 : * Check if the tuple is created by the current transaction. Throws an
171 : * error if the slot doesn't contain the storage tuple.
172 : */
173 : bool (*is_current_xact_tuple) (TupleTableSlot *slot);
174 :
175 : /*
176 : * Make the contents of the slot solely depend on the slot, and not on
177 : * underlying resources (like another memory context, buffers, etc).
178 : */
179 : void (*materialize) (TupleTableSlot *slot);
180 :
181 : /*
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.
185 : */
186 : void (*copyslot) (TupleTableSlot *dstslot, TupleTableSlot *srcslot);
187 :
188 : /*
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
192 : * NULL.
193 : */
194 : HeapTuple (*get_heap_tuple) (TupleTableSlot *slot);
195 :
196 : /*
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
200 : * set it as NULL.
201 : */
202 : MinimalTuple (*get_minimal_tuple) (TupleTableSlot *slot);
203 :
204 : /*
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.
211 : */
212 : HeapTuple (*copy_heap_tuple) (TupleTableSlot *slot);
213 :
214 : /*
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.
221 : */
222 : MinimalTuple (*copy_minimal_tuple) (TupleTableSlot *slot);
223 : };
224 :
225 : /*
226 : * Predefined TupleTableSlotOps for various types of TupleTableSlotOps. The
227 : * same are used to identify the type of a given slot.
228 : */
229 : extern PGDLLIMPORT const TupleTableSlotOps TTSOpsVirtual;
230 : extern PGDLLIMPORT const TupleTableSlotOps TTSOpsHeapTuple;
231 : extern PGDLLIMPORT const TupleTableSlotOps TTSOpsMinimalTuple;
232 : extern PGDLLIMPORT const TupleTableSlotOps TTSOpsBufferHeapTuple;
233 :
234 : #define TTS_IS_VIRTUAL(slot) ((slot)->tts_ops == &TTSOpsVirtual)
235 : #define TTS_IS_HEAPTUPLE(slot) ((slot)->tts_ops == &TTSOpsHeapTuple)
236 : #define TTS_IS_MINIMALTUPLE(slot) ((slot)->tts_ops == &TTSOpsMinimalTuple)
237 : #define TTS_IS_BUFFERTUPLE(slot) ((slot)->tts_ops == &TTSOpsBufferHeapTuple)
238 :
239 :
240 : /*
241 : * Tuple table slot implementations.
242 : */
243 :
244 : typedef struct VirtualTupleTableSlot
245 : {
246 : pg_node_attr(abstract)
247 :
248 : TupleTableSlot base;
249 :
250 : char *data; /* data for materialized slots */
251 : } VirtualTupleTableSlot;
252 :
253 : typedef struct HeapTupleTableSlot
254 : {
255 : pg_node_attr(abstract)
256 :
257 : TupleTableSlot base;
258 :
259 : #define FIELDNO_HEAPTUPLETABLESLOT_TUPLE 1
260 : HeapTuple tuple; /* physical tuple */
261 : #define FIELDNO_HEAPTUPLETABLESLOT_OFF 2
262 : uint32 off; /* saved state for slot_deform_heap_tuple */
263 : HeapTupleData tupdata; /* optional workspace for storing tuple */
264 : } HeapTupleTableSlot;
265 :
266 : /* heap tuple residing in a buffer */
267 : typedef struct BufferHeapTupleTableSlot
268 : {
269 : pg_node_attr(abstract)
270 :
271 : HeapTupleTableSlot base;
272 :
273 : /*
274 : * If buffer is not InvalidBuffer, then the slot is holding a pin on the
275 : * indicated buffer page; drop the pin when we release the slot's
276 : * reference to that buffer. (TTS_FLAG_SHOULDFREE should not be set in
277 : * such a case, since presumably base.tuple is pointing into the buffer.)
278 : */
279 : Buffer buffer; /* tuple's buffer, or InvalidBuffer */
280 : } BufferHeapTupleTableSlot;
281 :
282 : typedef struct MinimalTupleTableSlot
283 : {
284 : pg_node_attr(abstract)
285 :
286 : TupleTableSlot base;
287 :
288 : /*
289 : * In a minimal slot tuple points at minhdr and the fields of that struct
290 : * are set correctly for access to the minimal tuple; in particular,
291 : * minhdr.t_data points MINIMAL_TUPLE_OFFSET bytes before mintuple. This
292 : * allows column extraction to treat the case identically to regular
293 : * physical tuples.
294 : */
295 : #define FIELDNO_MINIMALTUPLETABLESLOT_TUPLE 1
296 : HeapTuple tuple; /* tuple wrapper */
297 : MinimalTuple mintuple; /* minimal tuple, or NULL if none */
298 : HeapTupleData minhdr; /* workspace for minimal-tuple-only case */
299 : #define FIELDNO_MINIMALTUPLETABLESLOT_OFF 4
300 : uint32 off; /* saved state for slot_deform_heap_tuple */
301 : } MinimalTupleTableSlot;
302 :
303 : /*
304 : * TupIsNull -- is a TupleTableSlot empty?
305 : */
306 : #define TupIsNull(slot) \
307 : ((slot) == NULL || TTS_EMPTY(slot))
308 :
309 : /* in executor/execTuples.c */
310 : extern TupleTableSlot *MakeTupleTableSlot(TupleDesc tupleDesc,
311 : const TupleTableSlotOps *tts_ops);
312 : extern TupleTableSlot *ExecAllocTableSlot(List **tupleTable, TupleDesc desc,
313 : const TupleTableSlotOps *tts_ops);
314 : extern void ExecResetTupleTable(List *tupleTable, bool shouldFree);
315 : extern TupleTableSlot *MakeSingleTupleTableSlot(TupleDesc tupdesc,
316 : const TupleTableSlotOps *tts_ops);
317 : extern void ExecDropSingleTupleTableSlot(TupleTableSlot *slot);
318 : extern void ExecSetSlotDescriptor(TupleTableSlot *slot, TupleDesc tupdesc);
319 : extern TupleTableSlot *ExecStoreHeapTuple(HeapTuple tuple,
320 : TupleTableSlot *slot,
321 : bool shouldFree);
322 : extern void ExecForceStoreHeapTuple(HeapTuple tuple,
323 : TupleTableSlot *slot,
324 : bool shouldFree);
325 : extern TupleTableSlot *ExecStoreBufferHeapTuple(HeapTuple tuple,
326 : TupleTableSlot *slot,
327 : Buffer buffer);
328 : extern TupleTableSlot *ExecStorePinnedBufferHeapTuple(HeapTuple tuple,
329 : TupleTableSlot *slot,
330 : Buffer buffer);
331 : extern TupleTableSlot *ExecStoreMinimalTuple(MinimalTuple mtup,
332 : TupleTableSlot *slot,
333 : bool shouldFree);
334 : extern void ExecForceStoreMinimalTuple(MinimalTuple mtup, TupleTableSlot *slot,
335 : bool shouldFree);
336 : extern TupleTableSlot *ExecStoreVirtualTuple(TupleTableSlot *slot);
337 : extern TupleTableSlot *ExecStoreAllNullTuple(TupleTableSlot *slot);
338 : extern void ExecStoreHeapTupleDatum(Datum data, TupleTableSlot *slot);
339 : extern HeapTuple ExecFetchSlotHeapTuple(TupleTableSlot *slot, bool materialize, bool *shouldFree);
340 : extern MinimalTuple ExecFetchSlotMinimalTuple(TupleTableSlot *slot,
341 : bool *shouldFree);
342 : extern Datum ExecFetchSlotHeapTupleDatum(TupleTableSlot *slot);
343 : extern void slot_getmissingattrs(TupleTableSlot *slot, int startAttNum,
344 : int lastAttNum);
345 : extern void slot_getsomeattrs_int(TupleTableSlot *slot, int attnum);
346 :
347 :
348 : #ifndef FRONTEND
349 :
350 : /*
351 : * This function forces the entries of the slot's Datum/isnull arrays to be
352 : * valid at least up through the attnum'th entry.
353 : */
354 : static inline void
355 195188842 : slot_getsomeattrs(TupleTableSlot *slot, int attnum)
356 : {
357 195188842 : if (slot->tts_nvalid < attnum)
358 155024746 : slot_getsomeattrs_int(slot, attnum);
359 195188842 : }
360 :
361 : /*
362 : * slot_getallattrs
363 : * This function forces all the entries of the slot's Datum/isnull
364 : * arrays to be valid. The caller may then extract data directly
365 : * from those arrays instead of using slot_getattr.
366 : */
367 : static inline void
368 15333340 : slot_getallattrs(TupleTableSlot *slot)
369 : {
370 15333340 : slot_getsomeattrs(slot, slot->tts_tupleDescriptor->natts);
371 15333340 : }
372 :
373 :
374 : /*
375 : * slot_attisnull
376 : *
377 : * Detect whether an attribute of the slot is null, without actually fetching
378 : * it.
379 : */
380 : static inline bool
381 8578936 : slot_attisnull(TupleTableSlot *slot, int attnum)
382 : {
383 : Assert(attnum > 0);
384 :
385 8578936 : if (attnum > slot->tts_nvalid)
386 6699398 : slot_getsomeattrs(slot, attnum);
387 :
388 8578936 : return slot->tts_isnull[attnum - 1];
389 : }
390 :
391 : /*
392 : * slot_getattr - fetch one attribute of the slot's contents.
393 : */
394 : static inline Datum
395 77247150 : slot_getattr(TupleTableSlot *slot, int attnum,
396 : bool *isnull)
397 : {
398 : Assert(attnum > 0);
399 :
400 77247150 : if (attnum > slot->tts_nvalid)
401 50556802 : slot_getsomeattrs(slot, attnum);
402 :
403 77247150 : *isnull = slot->tts_isnull[attnum - 1];
404 :
405 77247150 : return slot->tts_values[attnum - 1];
406 : }
407 :
408 : /*
409 : * slot_getsysattr - fetch a system attribute of the slot's current tuple.
410 : *
411 : * If the slot type does not contain system attributes, this will throw an
412 : * error. Hence before calling this function, callers should make sure that
413 : * the slot type is the one that supports system attributes.
414 : */
415 : static inline Datum
416 6525140 : slot_getsysattr(TupleTableSlot *slot, int attnum, bool *isnull)
417 : {
418 : Assert(attnum < 0); /* caller error */
419 :
420 6525140 : if (attnum == TableOidAttributeNumber)
421 : {
422 2239624 : *isnull = false;
423 2239624 : return ObjectIdGetDatum(slot->tts_tableOid);
424 : }
425 4285516 : else if (attnum == SelfItemPointerAttributeNumber)
426 : {
427 4285100 : *isnull = false;
428 4285100 : return PointerGetDatum(&slot->tts_tid);
429 : }
430 :
431 : /* Fetch the system attribute from the underlying tuple. */
432 416 : return slot->tts_ops->getsysattr(slot, attnum, isnull);
433 : }
434 :
435 : /*
436 : * slot_is_current_xact_tuple - check if the slot's current tuple is created
437 : * by the current transaction.
438 : *
439 : * If the slot does not contain a storage tuple, this will throw an error.
440 : * Hence before calling this function, callers should make sure that the
441 : * slot type supports storage tuples and that there is currently one inside
442 : * the slot.
443 : */
444 : static inline bool
445 912 : slot_is_current_xact_tuple(TupleTableSlot *slot)
446 : {
447 912 : return slot->tts_ops->is_current_xact_tuple(slot);
448 : }
449 :
450 : /*
451 : * ExecClearTuple - clear the slot's contents
452 : */
453 : static inline TupleTableSlot *
454 136528950 : ExecClearTuple(TupleTableSlot *slot)
455 : {
456 136528950 : slot->tts_ops->clear(slot);
457 :
458 136528950 : return slot;
459 : }
460 :
461 : /* ExecMaterializeSlot - force a slot into the "materialized" state.
462 : *
463 : * This causes the slot's tuple to be a local copy not dependent on any
464 : * external storage (i.e. pointing into a Buffer, or having allocations in
465 : * another memory context).
466 : *
467 : * A typical use for this operation is to prepare a computed tuple for being
468 : * stored on disk. The original data may or may not be virtual, but in any
469 : * case we need a private copy for heap_insert to scribble on.
470 : */
471 : static inline void
472 14852248 : ExecMaterializeSlot(TupleTableSlot *slot)
473 : {
474 14852248 : slot->tts_ops->materialize(slot);
475 14852248 : }
476 :
477 : /*
478 : * ExecCopySlotHeapTuple - return HeapTuple allocated in caller's context
479 : */
480 : static inline HeapTuple
481 19554250 : ExecCopySlotHeapTuple(TupleTableSlot *slot)
482 : {
483 : Assert(!TTS_EMPTY(slot));
484 :
485 19554250 : return slot->tts_ops->copy_heap_tuple(slot);
486 : }
487 :
488 : /*
489 : * ExecCopySlotMinimalTuple - return MinimalTuple allocated in caller's context
490 : */
491 : static inline MinimalTuple
492 15385072 : ExecCopySlotMinimalTuple(TupleTableSlot *slot)
493 : {
494 15385072 : return slot->tts_ops->copy_minimal_tuple(slot);
495 : }
496 :
497 : /*
498 : * ExecCopySlot - copy one slot's contents into another.
499 : *
500 : * If a source's system attributes are supposed to be accessed in the target
501 : * slot, the target slot and source slot types need to match.
502 : *
503 : * Currently, 'dstslot' and 'srcslot' must have the same number of attributes.
504 : * Future work could see this relaxed to allow the source to contain
505 : * additional attributes and have the code here only copy over the leading
506 : * attributes.
507 : */
508 : static inline TupleTableSlot *
509 11755352 : ExecCopySlot(TupleTableSlot *dstslot, TupleTableSlot *srcslot)
510 : {
511 : Assert(!TTS_EMPTY(srcslot));
512 : Assert(srcslot != dstslot);
513 : Assert(dstslot->tts_tupleDescriptor->natts ==
514 : srcslot->tts_tupleDescriptor->natts);
515 :
516 11755352 : dstslot->tts_ops->copyslot(dstslot, srcslot);
517 :
518 11755352 : return dstslot;
519 : }
520 :
521 : #endif /* FRONTEND */
522 :
523 : #endif /* TUPTABLE_H */
|
