Age Owner Branch data TLA Line data Source code
1 : : /*-------------------------------------------------------------------------
2 : : *
3 : : * itemptr.h
4 : : * POSTGRES disk item pointer definitions.
5 : : *
6 : : *
7 : : * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
8 : : * Portions Copyright (c) 1994, Regents of the University of California
9 : : *
10 : : * src/include/storage/itemptr.h
11 : : *
12 : : *-------------------------------------------------------------------------
13 : : */
14 : : #ifndef ITEMPTR_H
15 : : #define ITEMPTR_H
16 : :
17 : : #include "storage/block.h"
18 : : #include "storage/off.h"
19 : :
20 : : /*
21 : : * ItemPointer:
22 : : *
23 : : * This is a pointer to an item within a disk page of a known file
24 : : * (for example, a cross-link from an index to its parent table).
25 : : * ip_blkid tells us which block, ip_posid tells us which entry in
26 : : * the linp (ItemIdData) array we want.
27 : : *
28 : : * Note: because there is an item pointer in each tuple header and index
29 : : * tuple header on disk, it's very important not to waste space with
30 : : * structure padding bytes. The struct is designed to be six bytes long
31 : : * (it contains three int16 fields) but a few compilers will pad it to
32 : : * eight bytes unless coerced. We apply appropriate persuasion where
33 : : * possible. If your compiler can't be made to play along, you'll waste
34 : : * lots of space.
35 : : */
36 : : typedef struct ItemPointerData
37 : : {
38 : : BlockIdData ip_blkid;
39 : : OffsetNumber ip_posid;
40 : : }
41 : :
42 : : /* If compiler understands packed and aligned pragmas, use those */
43 : : #if defined(pg_attribute_packed) && defined(pg_attribute_aligned)
44 : : pg_attribute_packed()
45 : : pg_attribute_aligned(2)
46 : : #endif
47 : : ItemPointerData;
48 : :
49 : : typedef ItemPointerData *ItemPointer;
50 : :
51 : : /* ----------------
52 : : * special values used in heap tuples (t_ctid)
53 : : * ----------------
54 : : */
55 : :
56 : : /*
57 : : * If a heap tuple holds a speculative insertion token rather than a real
58 : : * TID, ip_posid is set to SpecTokenOffsetNumber, and the token is stored in
59 : : * ip_blkid. SpecTokenOffsetNumber must be higher than MaxOffsetNumber, so
60 : : * that it can be distinguished from a valid offset number in a regular item
61 : : * pointer.
62 : : */
63 : : #define SpecTokenOffsetNumber 0xfffe
64 : :
65 : : /*
66 : : * When a tuple is moved to a different partition by UPDATE, the t_ctid of
67 : : * the old tuple version is set to this magic value.
68 : : */
69 : : #define MovedPartitionsOffsetNumber 0xfffd
70 : : #define MovedPartitionsBlockNumber InvalidBlockNumber
71 : :
72 : :
73 : : /* ----------------
74 : : * support functions
75 : : * ----------------
76 : : */
77 : :
78 : : /*
79 : : * ItemPointerIsValid
80 : : * True iff the disk item pointer is not NULL.
81 : : */
82 : : static inline bool
1202 peter@eisentraut.org 83 :CBC 561506570 : ItemPointerIsValid(const ItemPointerData *pointer)
84 : : {
33 peter@eisentraut.org 85 [ + + + + ]:GNC 561506570 : return pointer && pointer->ip_posid != 0;
86 : : }
87 : :
88 : : /*
89 : : * ItemPointerGetBlockNumberNoCheck
90 : : * Returns the block number of a disk item pointer.
91 : : */
92 : : static inline BlockNumber
1202 peter@eisentraut.org 93 :CBC 286972331 : ItemPointerGetBlockNumberNoCheck(const ItemPointerData *pointer)
94 : : {
95 : 286972331 : return BlockIdGetBlockNumber(&pointer->ip_blkid);
96 : : }
97 : :
98 : : /*
99 : : * ItemPointerGetBlockNumber
100 : : * As above, but verifies that the item pointer looks valid.
101 : : */
102 : : static inline BlockNumber
103 : 163723675 : ItemPointerGetBlockNumber(const ItemPointerData *pointer)
104 : : {
105 [ - + ]: 163723675 : Assert(ItemPointerIsValid(pointer));
106 : 163723675 : return ItemPointerGetBlockNumberNoCheck(pointer);
107 : : }
108 : :
109 : : /*
110 : : * ItemPointerGetOffsetNumberNoCheck
111 : : * Returns the offset number of a disk item pointer.
112 : : */
113 : : static inline OffsetNumber
114 : 972208384 : ItemPointerGetOffsetNumberNoCheck(const ItemPointerData *pointer)
115 : : {
116 : 972208384 : return pointer->ip_posid;
117 : : }
118 : :
119 : : /*
120 : : * ItemPointerGetOffsetNumber
121 : : * As above, but verifies that the item pointer looks valid.
122 : : */
123 : : static inline OffsetNumber
124 : 118478958 : ItemPointerGetOffsetNumber(const ItemPointerData *pointer)
125 : : {
126 [ - + ]: 118478958 : Assert(ItemPointerIsValid(pointer));
127 : 118478958 : return ItemPointerGetOffsetNumberNoCheck(pointer);
128 : : }
129 : :
130 : : /*
131 : : * ItemPointerSet
132 : : * Sets a disk item pointer to the specified block and offset.
133 : : */
134 : : static inline void
135 : 172724295 : ItemPointerSet(ItemPointerData *pointer, BlockNumber blockNumber, OffsetNumber offNum)
136 : : {
33 peter@eisentraut.org 137 [ - + ]:GNC 172724295 : Assert(pointer);
1202 peter@eisentraut.org 138 :CBC 172724295 : BlockIdSet(&pointer->ip_blkid, blockNumber);
139 : 172724295 : pointer->ip_posid = offNum;
140 : 172724295 : }
141 : :
142 : : /*
143 : : * ItemPointerSetBlockNumber
144 : : * Sets a disk item pointer to the specified block.
145 : : */
146 : : static inline void
147 : 77594420 : ItemPointerSetBlockNumber(ItemPointerData *pointer, BlockNumber blockNumber)
148 : : {
33 peter@eisentraut.org 149 [ - + ]:GNC 77594420 : Assert(pointer);
1202 peter@eisentraut.org 150 :CBC 77594420 : BlockIdSet(&pointer->ip_blkid, blockNumber);
151 : 77594420 : }
152 : :
153 : : /*
154 : : * ItemPointerSetOffsetNumber
155 : : * Sets a disk item pointer to the specified offset.
156 : : */
157 : : static inline void
158 : 183000935 : ItemPointerSetOffsetNumber(ItemPointerData *pointer, OffsetNumber offsetNumber)
159 : : {
33 peter@eisentraut.org 160 [ - + ]:GNC 183000935 : Assert(pointer);
1202 peter@eisentraut.org 161 :CBC 183000935 : pointer->ip_posid = offsetNumber;
162 : 183000935 : }
163 : :
164 : : /*
165 : : * ItemPointerCopy
166 : : * Copies the contents of one disk item pointer to another.
167 : : *
168 : : * Should there ever be padding in an ItemPointer this would need to be handled
169 : : * differently as it's used as hash key.
170 : : */
171 : : static inline void
172 : 16087339 : ItemPointerCopy(const ItemPointerData *fromPointer, ItemPointerData *toPointer)
173 : : {
33 peter@eisentraut.org 174 [ - + ]:GNC 16087339 : Assert(toPointer);
175 [ - + ]: 16087339 : Assert(fromPointer);
1202 peter@eisentraut.org 176 :CBC 16087339 : *toPointer = *fromPointer;
177 : 16087339 : }
178 : :
179 : : /*
180 : : * ItemPointerSetInvalid
181 : : * Sets a disk item pointer to be invalid.
182 : : */
183 : : static inline void
184 : 141324057 : ItemPointerSetInvalid(ItemPointerData *pointer)
185 : : {
33 peter@eisentraut.org 186 [ - + ]:GNC 141324057 : Assert(pointer);
1202 peter@eisentraut.org 187 :CBC 141324057 : BlockIdSet(&pointer->ip_blkid, InvalidBlockNumber);
188 : 141324057 : pointer->ip_posid = InvalidOffsetNumber;
189 : 141324057 : }
190 : :
191 : : /*
192 : : * ItemPointerIndicatesMovedPartitions
193 : : * True iff the block number indicates the tuple has moved to another
194 : : * partition.
195 : : */
196 : : static inline bool
197 : 124049 : ItemPointerIndicatesMovedPartitions(const ItemPointerData *pointer)
198 : : {
199 : : return
200 [ + + + - ]: 124062 : ItemPointerGetOffsetNumber(pointer) == MovedPartitionsOffsetNumber &&
201 : 13 : ItemPointerGetBlockNumberNoCheck(pointer) == MovedPartitionsBlockNumber;
202 : : }
203 : :
204 : : /*
205 : : * ItemPointerSetMovedPartitions
206 : : * Indicate that the item referenced by the itempointer has moved into a
207 : : * different partition.
208 : : */
209 : : static inline void
210 : 631 : ItemPointerSetMovedPartitions(ItemPointerData *pointer)
211 : : {
212 : 631 : ItemPointerSet(pointer, MovedPartitionsBlockNumber, MovedPartitionsOffsetNumber);
213 : 631 : }
214 : :
215 : : /* ----------------
216 : : * externs
217 : : * ----------------
218 : : */
219 : :
220 : : extern bool ItemPointerEquals(ItemPointer pointer1, ItemPointer pointer2);
221 : : extern int32 ItemPointerCompare(ItemPointer arg1, ItemPointer arg2);
222 : : extern void ItemPointerInc(ItemPointer pointer);
223 : : extern void ItemPointerDec(ItemPointer pointer);
224 : :
225 : : /* ----------------
226 : : * Datum conversion functions
227 : : * ----------------
228 : : */
229 : :
230 : : static inline ItemPointer
987 231 : 21541701 : DatumGetItemPointer(Datum X)
232 : : {
233 : 21541701 : return (ItemPointer) DatumGetPointer(X);
234 : : }
235 : :
236 : : static inline Datum
237 : 11929 : ItemPointerGetDatum(const ItemPointerData *X)
238 : : {
239 : 11929 : return PointerGetDatum(X);
240 : : }
241 : :
242 : : #define PG_GETARG_ITEMPOINTER(n) DatumGetItemPointer(PG_GETARG_DATUM(n))
243 : : #define PG_RETURN_ITEMPOINTER(x) return ItemPointerGetDatum(x)
244 : :
245 : : #endif /* ITEMPTR_H */
|
