Line data Source code
1 : /*-------------------------------------------------------------------------
2 : *
3 : * itemptr.h
4 : * POSTGRES disk item pointer definitions.
5 : *
6 : *
7 : * Portions Copyright (c) 1996-2026, 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
83 11290908 : ItemPointerIsValid(const ItemPointerData *pointer)
84 : {
85 11290908 : 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
93 240325675 : ItemPointerGetBlockNumberNoCheck(const ItemPointerData *pointer)
94 : {
95 240325675 : 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 140081169 : ItemPointerGetBlockNumber(const ItemPointerData *pointer)
104 : {
105 : Assert(ItemPointerIsValid(pointer));
106 140081169 : return ItemPointerGetBlockNumberNoCheck(pointer);
107 : }
108 :
109 : /*
110 : * ItemPointerGetOffsetNumberNoCheck
111 : * Returns the offset number of a disk item pointer.
112 : */
113 : static inline OffsetNumber
114 494643106 : ItemPointerGetOffsetNumberNoCheck(const ItemPointerData *pointer)
115 : {
116 494643106 : 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 98581858 : ItemPointerGetOffsetNumber(const ItemPointerData *pointer)
125 : {
126 : Assert(ItemPointerIsValid(pointer));
127 98581858 : 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 155670521 : ItemPointerSet(ItemPointerData *pointer, BlockNumber blockNumber, OffsetNumber offNum)
136 : {
137 : Assert(pointer);
138 155670521 : BlockIdSet(&pointer->ip_blkid, blockNumber);
139 155670521 : pointer->ip_posid = offNum;
140 155670521 : }
141 :
142 : /*
143 : * ItemPointerSetBlockNumber
144 : * Sets a disk item pointer to the specified block.
145 : */
146 : static inline void
147 42816053 : ItemPointerSetBlockNumber(ItemPointerData *pointer, BlockNumber blockNumber)
148 : {
149 : Assert(pointer);
150 42816053 : BlockIdSet(&pointer->ip_blkid, blockNumber);
151 42816053 : }
152 :
153 : /*
154 : * ItemPointerSetOffsetNumber
155 : * Sets a disk item pointer to the specified offset.
156 : */
157 : static inline void
158 158791949 : ItemPointerSetOffsetNumber(ItemPointerData *pointer, OffsetNumber offsetNumber)
159 : {
160 : Assert(pointer);
161 158791949 : pointer->ip_posid = offsetNumber;
162 158791949 : }
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 7889410 : ItemPointerCopy(const ItemPointerData *fromPointer, ItemPointerData *toPointer)
173 : {
174 : Assert(toPointer);
175 : Assert(fromPointer);
176 7889410 : *toPointer = *fromPointer;
177 7889410 : }
178 :
179 : /*
180 : * ItemPointerSetInvalid
181 : * Sets a disk item pointer to be invalid.
182 : */
183 : static inline void
184 146495016 : ItemPointerSetInvalid(ItemPointerData *pointer)
185 : {
186 : Assert(pointer);
187 146495016 : BlockIdSet(&pointer->ip_blkid, InvalidBlockNumber);
188 146495016 : pointer->ip_posid = InvalidOffsetNumber;
189 146495016 : }
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 13568 : ItemPointerIndicatesMovedPartitions(const ItemPointerData *pointer)
198 : {
199 : return
200 13581 : 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 636 : ItemPointerSetMovedPartitions(ItemPointerData *pointer)
211 : {
212 636 : ItemPointerSet(pointer, MovedPartitionsBlockNumber, MovedPartitionsOffsetNumber);
213 636 : }
214 :
215 : /* ----------------
216 : * externs
217 : * ----------------
218 : */
219 :
220 : extern bool ItemPointerEquals(const ItemPointerData *pointer1, const ItemPointerData *pointer2);
221 : extern int32 ItemPointerCompare(const ItemPointerData *arg1, const ItemPointerData *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
231 21443826 : DatumGetItemPointer(Datum X)
232 : {
233 21443826 : return (ItemPointer) DatumGetPointer(X);
234 : }
235 :
236 : static inline Datum
237 13055 : ItemPointerGetDatum(const ItemPointerData *X)
238 : {
239 13055 : 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 */
|
