PostgreSQL Source Code  git master
itemptr.h
Go to the documentation of this file.
1 /*-------------------------------------------------------------------------
2  *
3  * itemptr.h
4  * POSTGRES disk item pointer definitions.
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/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 {
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
48 
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
84 {
85  return PointerIsValid(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
94 {
95  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
104 {
105  Assert(ItemPointerIsValid(pointer));
106  return ItemPointerGetBlockNumberNoCheck(pointer);
107 }
108 
109 /*
110  * ItemPointerGetOffsetNumberNoCheck
111  * Returns the offset number of a disk item pointer.
112  */
113 static inline OffsetNumber
115 {
116  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
125 {
126  Assert(ItemPointerIsValid(pointer));
127  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
136 {
137  Assert(PointerIsValid(pointer));
138  BlockIdSet(&pointer->ip_blkid, blockNumber);
139  pointer->ip_posid = offNum;
140 }
141 
142 /*
143  * ItemPointerSetBlockNumber
144  * Sets a disk item pointer to the specified block.
145  */
146 static inline void
148 {
149  Assert(PointerIsValid(pointer));
150  BlockIdSet(&pointer->ip_blkid, blockNumber);
151 }
152 
153 /*
154  * ItemPointerSetOffsetNumber
155  * Sets a disk item pointer to the specified offset.
156  */
157 static inline void
159 {
160  Assert(PointerIsValid(pointer));
161  pointer->ip_posid = offsetNumber;
162 }
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 ItemPointerCopy(const ItemPointerData *fromPointer, ItemPointerData *toPointer)
173 {
174  Assert(PointerIsValid(toPointer));
175  Assert(PointerIsValid(fromPointer));
176  *toPointer = *fromPointer;
177 }
178 
179 /*
180  * ItemPointerSetInvalid
181  * Sets a disk item pointer to be invalid.
182  */
183 static inline void
185 {
186  Assert(PointerIsValid(pointer));
188  pointer->ip_posid = InvalidOffsetNumber;
189 }
190 
191 /*
192  * ItemPointerIndicatesMovedPartitions
193  * True iff the block number indicates the tuple has moved to another
194  * partition.
195  */
196 static inline bool
198 {
199  return
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
211 {
213 }
214 
215 /* ----------------
216  * externs
217  * ----------------
218  */
219 
220 extern bool ItemPointerEquals(ItemPointer pointer1, ItemPointer pointer2);
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
232 {
233  return (ItemPointer) DatumGetPointer(X);
234 }
235 
236 static inline Datum
238 {
239  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 */
uint32 BlockNumber
Definition: block.h:31
#define InvalidBlockNumber
Definition: block.h:33
static void BlockIdSet(BlockIdData *blockId, BlockNumber blockNumber)
Definition: block.h:81
static BlockNumber BlockIdGetBlockNumber(const BlockIdData *blockId)
Definition: block.h:103
signed int int32
Definition: c.h:481
#define PointerIsValid(pointer)
Definition: c.h:750
void ItemPointerDec(ItemPointer pointer)
Definition: itemptr.c:114
static void ItemPointerSet(ItemPointerData *pointer, BlockNumber blockNumber, OffsetNumber offNum)
Definition: itemptr.h:135
static void ItemPointerSetInvalid(ItemPointerData *pointer)
Definition: itemptr.h:184
static Datum ItemPointerGetDatum(const ItemPointerData *X)
Definition: itemptr.h:237
static void ItemPointerSetOffsetNumber(ItemPointerData *pointer, OffsetNumber offsetNumber)
Definition: itemptr.h:158
static void ItemPointerSetBlockNumber(ItemPointerData *pointer, BlockNumber blockNumber)
Definition: itemptr.h:147
static OffsetNumber ItemPointerGetOffsetNumber(const ItemPointerData *pointer)
Definition: itemptr.h:124
static bool ItemPointerIndicatesMovedPartitions(const ItemPointerData *pointer)
Definition: itemptr.h:197
#define MovedPartitionsOffsetNumber
Definition: itemptr.h:69
static void ItemPointerSetMovedPartitions(ItemPointerData *pointer)
Definition: itemptr.h:210
static OffsetNumber ItemPointerGetOffsetNumberNoCheck(const ItemPointerData *pointer)
Definition: itemptr.h:114
static BlockNumber ItemPointerGetBlockNumber(const ItemPointerData *pointer)
Definition: itemptr.h:103
static BlockNumber ItemPointerGetBlockNumberNoCheck(const ItemPointerData *pointer)
Definition: itemptr.h:93
void ItemPointerInc(ItemPointer pointer)
Definition: itemptr.c:84
ItemPointerData * ItemPointer
Definition: itemptr.h:49
int32 ItemPointerCompare(ItemPointer arg1, ItemPointer arg2)
Definition: itemptr.c:51
struct ItemPointerData ItemPointerData
#define MovedPartitionsBlockNumber
Definition: itemptr.h:70
bool ItemPointerEquals(ItemPointer pointer1, ItemPointer pointer2)
Definition: itemptr.c:35
static ItemPointer DatumGetItemPointer(Datum X)
Definition: itemptr.h:231
static void ItemPointerCopy(const ItemPointerData *fromPointer, ItemPointerData *toPointer)
Definition: itemptr.h:172
static bool ItemPointerIsValid(const ItemPointerData *pointer)
Definition: itemptr.h:83
Assert(fmt[strlen(fmt) - 1] !='\n')
#define InvalidOffsetNumber
Definition: off.h:26
uint16 OffsetNumber
Definition: off.h:24
static Datum PointerGetDatum(const void *X)
Definition: postgres.h:322
uintptr_t Datum
Definition: postgres.h:64
static Pointer DatumGetPointer(Datum X)
Definition: postgres.h:312
OffsetNumber ip_posid
Definition: itemptr.h:39
BlockIdData ip_blkid
Definition: itemptr.h:38