PostgreSQL Source Code  git master
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros
tuptable.h
Go to the documentation of this file.
1 /*-------------------------------------------------------------------------
2  *
3  * tuptable.h
4  * tuple table support stuff
5  *
6  *
7  * Portions Copyright (c) 1996-2017, 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/tupdesc.h"
19 #include "storage/buf.h"
20 
21 /*----------
22  * The executor stores tuples in a "tuple table" which is a List 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  */
113 typedef struct TupleTableSlot
114 {
116  bool tts_isempty; /* true = slot is empty */
117  bool tts_shouldFree; /* should pfree tts_tuple? */
118  bool tts_shouldFreeMin; /* should pfree tts_mintuple? */
119  bool tts_slow; /* saved state for slot_deform_tuple */
120  HeapTuple tts_tuple; /* physical tuple, or NULL if virtual */
121  TupleDesc tts_tupleDescriptor; /* slot's tuple descriptor */
122  MemoryContext tts_mcxt; /* slot itself is in this context */
123  Buffer tts_buffer; /* tuple's buffer, or InvalidBuffer */
124  int tts_nvalid; /* # of valid values in tts_values */
125  Datum *tts_values; /* current per-attribute values */
126  bool *tts_isnull; /* current per-attribute isnull flags */
127  MinimalTuple tts_mintuple; /* minimal tuple, or NULL if none */
128  HeapTupleData tts_minhdr; /* workspace for minimal-tuple-only case */
129  long tts_off; /* saved state for slot_deform_tuple */
131 
132 #define TTS_HAS_PHYSICAL_TUPLE(slot) \
133  ((slot)->tts_tuple != NULL && (slot)->tts_tuple != &((slot)->tts_minhdr))
134 
135 /*
136  * TupIsNull -- is a TupleTableSlot empty?
137  */
138 #define TupIsNull(slot) \
139  ((slot) == NULL || (slot)->tts_isempty)
140 
141 /* in executor/execTuples.c */
142 extern TupleTableSlot *MakeTupleTableSlot(void);
143 extern TupleTableSlot *ExecAllocTableSlot(List **tupleTable);
144 extern void ExecResetTupleTable(List *tupleTable, bool shouldFree);
147 extern void ExecSetSlotDescriptor(TupleTableSlot *slot, TupleDesc tupdesc);
149  TupleTableSlot *slot,
150  Buffer buffer,
151  bool shouldFree);
153  TupleTableSlot *slot,
154  bool shouldFree);
165  TupleTableSlot *srcslot);
166 
167 /* in access/common/heaptuple.c */
168 extern Datum slot_getattr(TupleTableSlot *slot, int attnum, bool *isnull);
169 extern void slot_getallattrs(TupleTableSlot *slot);
170 extern void slot_getsomeattrs(TupleTableSlot *slot, int attnum);
171 extern bool slot_attisnull(TupleTableSlot *slot, int attnum);
172 
173 #endif /* TUPTABLE_H */
TupleTableSlot * MakeSingleTupleTableSlot(TupleDesc tupdesc)
Definition: execTuples.c:199
bool slot_attisnull(TupleTableSlot *slot, int attnum)
Definition: heaptuple.c:1330
TupleTableSlot * ExecStoreVirtualTuple(TupleTableSlot *slot)
Definition: execTuples.c:488
void slot_getallattrs(TupleTableSlot *slot)
Definition: heaptuple.c:1239
bool tts_isempty
Definition: tuptable.h:116
Datum ExecFetchSlotTupleDatum(TupleTableSlot *slot)
Definition: execTuples.c:698
HeapTuple ExecCopySlotTuple(TupleTableSlot *slot)
Definition: execTuples.c:545
TupleTableSlot * ExecStoreAllNullTuple(TupleTableSlot *slot)
Definition: execTuples.c:512
void ExecResetTupleTable(List *tupleTable, bool shouldFree)
Definition: execTuples.c:156
Datum slot_getattr(TupleTableSlot *slot, int attnum, bool *isnull)
Definition: heaptuple.c:1143
void ExecSetSlotDescriptor(TupleTableSlot *slot, TupleDesc tupdesc)
Definition: execTuples.c:247
bool tts_shouldFreeMin
Definition: tuptable.h:118
MemoryContext tts_mcxt
Definition: tuptable.h:122
Datum * tts_values
Definition: tuptable.h:125
NodeTag
Definition: nodes.h:26
NodeTag type
Definition: tuptable.h:115
MinimalTuple ExecFetchSlotMinimalTuple(TupleTableSlot *slot)
Definition: execTuples.c:652
HeapTupleData tts_minhdr
Definition: tuptable.h:128
bool * tts_isnull
Definition: tuptable.h:126
TupleTableSlot * ExecStoreTuple(HeapTuple tuple, TupleTableSlot *slot, Buffer buffer, bool shouldFree)
Definition: execTuples.c:320
bool tts_shouldFree
Definition: tuptable.h:117
void slot_getsomeattrs(TupleTableSlot *slot, int attnum)
Definition: heaptuple.c:1283
TupleDesc tts_tupleDescriptor
Definition: tuptable.h:121
uintptr_t Datum
Definition: postgres.h:372
HeapTuple ExecFetchSlotTuple(TupleTableSlot *slot)
Definition: execTuples.c:618
void ExecDropSingleTupleTableSlot(TupleTableSlot *slot)
Definition: execTuples.c:216
TupleTableSlot * ExecAllocTableSlot(List **tupleTable)
Definition: execTuples.c:137
struct TupleTableSlot TupleTableSlot
TupleTableSlot * ExecStoreMinimalTuple(MinimalTuple mtup, TupleTableSlot *slot, bool shouldFree)
Definition: execTuples.c:384
WalTimeSample buffer[LAG_TRACKER_BUFFER_SIZE]
Definition: walsender.c:207
MinimalTuple tts_mintuple
Definition: tuptable.h:127
TupleTableSlot * MakeTupleTableSlot(void)
Definition: execTuples.c:111
HeapTuple ExecMaterializeSlot(TupleTableSlot *slot)
Definition: execTuples.c:725
TupleTableSlot * ExecCopySlot(TupleTableSlot *dstslot, TupleTableSlot *srcslot)
Definition: execTuples.c:795
HeapTuple tts_tuple
Definition: tuptable.h:120
Buffer tts_buffer
Definition: tuptable.h:123
Definition: pg_list.h:45
int Buffer
Definition: buf.h:23
MinimalTuple ExecCopySlotMinimalTuple(TupleTableSlot *slot)
Definition: execTuples.c:577
TupleTableSlot * ExecClearTuple(TupleTableSlot *slot)
Definition: execTuples.c:439