| blob | e40082d144352226b71f69710f60e9714fb47185 |
1 /*-------------------------------------------------------------------------
2 *
3 * tuptable.h
4 * tuple table support stuff
5 *
6 *
7 * Portions Copyright (c) 1996-2009, PostgreSQL Global Development Group
8 * Portions Copyright (c) 1994, Regents of the University of California
9 *
10 * $PostgreSQL$
11 *
12 *-------------------------------------------------------------------------
13 */
14 #ifndef TUPTABLE_H
15 #define TUPTABLE_H
21 /*----------
22 * The executor stores tuples in a "tuple table" which is composed of
23 * independent TupleTableSlots. There are several cases we need to handle:
24 * 1. physical tuple in a disk buffer page
25 * 2. physical tuple constructed in palloc'ed memory
26 * 3. "minimal" physical tuple constructed in palloc'ed memory
27 * 4. "virtual" tuple consisting of Datum/isnull arrays
28 *
29 * The first two cases are similar in that they both deal with "materialized"
30 * tuples, but resource management is different. For a tuple in a disk page
31 * we need to hold a pin on the buffer until the TupleTableSlot's reference
32 * to the tuple is dropped; while for a palloc'd tuple we usually want the
33 * tuple pfree'd when the TupleTableSlot's reference is dropped.
34 *
35 * A "minimal" tuple is handled similarly to a palloc'd regular tuple.
36 * At present, minimal tuples never are stored in buffers, so there is no
37 * parallel to case 1. Note that a minimal tuple has no "system columns".
38 * (Actually, it could have an OID, but we have no need to access the OID.)
39 *
40 * A "virtual" tuple is an optimization used to minimize physical data
41 * copying in a nest of plan nodes. Any pass-by-reference Datums in the
42 * tuple point to storage that is not directly associated with the
43 * TupleTableSlot; generally they will point to part of a tuple stored in
44 * a lower plan node's output TupleTableSlot, or to a function result
45 * constructed in a plan node's per-tuple econtext. It is the responsibility
46 * of the generating plan node to be sure these resources are not released
47 * for as long as the virtual tuple needs to be valid. We only use virtual
48 * tuples in the result slots of plan nodes --- tuples to be copied anywhere
49 * else need to be "materialized" into physical tuples. Note also that a
50 * virtual tuple does not have any "system columns".
51 *
52 * It is also possible for a TupleTableSlot to hold both physical and minimal
53 * copies of a tuple. This is done when the slot is requested to provide
54 * the format other than the one it currently holds. (Originally we attempted
55 * to handle such requests by replacing one format with the other, but that
56 * had the fatal defect of invalidating any pass-by-reference Datums pointing
57 * into the existing slot contents.) Both copies must contain identical data
58 * payloads when this is the case.
59 *
60 * The Datum/isnull arrays of a TupleTableSlot serve double duty. When the
61 * slot contains a virtual tuple, they are the authoritative data. When the
62 * slot contains a physical tuple, the arrays contain data extracted from
63 * the tuple. (In this state, any pass-by-reference Datums point into
64 * the physical tuple.) The extracted information is built "lazily",
65 * ie, only as needed. This serves to avoid repeated extraction of data
66 * from the physical tuple.
67 *
68 * A TupleTableSlot can also be "empty", holding no valid data. This is
69 * the only valid state for a freshly-created slot that has not yet had a
70 * tuple descriptor assigned to it. In this state, tts_isempty must be
71 * TRUE, tts_shouldFree FALSE, tts_tuple NULL, tts_buffer InvalidBuffer,
72 * and tts_nvalid zero.
73 *
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.)
81 *
82 * When tts_shouldFree is true, the physical tuple is "owned" by the slot
83 * and should be freed when the slot's reference to the tuple is dropped.
84 *
85 * If tts_buffer is not InvalidBuffer, then the slot is holding a pin
86 * on the indicated buffer page; drop the pin when we release the
87 * slot's reference to that buffer. (tts_shouldFree should always be
88 * false in such a case, since presumably tts_tuple is pointing at the
89 * buffer page.)
90 *
91 * tts_nvalid indicates the number of valid columns in the tts_values/isnull
92 * arrays. When the slot is holding a "virtual" tuple this must be equal
93 * to the descriptor's natts. When the slot is holding a physical tuple
94 * this is equal to the number of columns we have extracted (we always
95 * extract columns from left to right, so there are no holes).
96 *
97 * tts_values/tts_isnull are allocated when a descriptor is assigned to the
98 * slot; they are of length equal to the descriptor's natts.
99 *
100 * tts_mintuple must always be NULL if the slot does not hold a "minimal"
101 * tuple. When it does, tts_mintuple points to the actual MinimalTupleData
102 * object (the thing to be pfree'd if tts_shouldFreeMin is true). If the slot
103 * has only a minimal and not also a regular physical tuple, then tts_tuple
104 * points at tts_minhdr and the fields of that struct are set correctly
105 * for access to the minimal tuple; in particular, tts_minhdr.t_data points
106 * MINIMAL_TUPLE_OFFSET bytes before tts_mintuple. This allows column
107 * extraction to treat the case identically to regular physical tuples.
108 *
109 * tts_slow/tts_off are saved state for slot_deform_tuple, and should not
110 * be touched by any other code.
111 *----------
112 */
114 {
132 #define TTS_HAS_PHYSICAL_TUPLE(slot) \
133 ((slot)->tts_tuple != NULL && (slot)->tts_tuple != &((slot)->tts_minhdr))
135 /*
136 * Tuple table data structure: an array of TupleTableSlots.
137 */
139 {
148 /*
149 * TupIsNull -- is a TupleTableSlot empty?
150 */
151 #define TupIsNull(slot) \
152 ((slot) == NULL || (slot)->tts_isempty)
154 /* in executor/execTuples.c */
163 Buffer buffer,
180 /* in access/common/heaptuple.c */