src/include/storage/itemptr.h

   1 /*-------------------------------------------------------------------------
   2  *
   3  * itemptr.h
   4  *        POSTGRES disk item pointer definitions.
   5  *
   6  *
   7  * Portions Copyright (c) 1996-2022, 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 ItemPointerIsValid(const ItemPointerData *pointer)
  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
  93 ItemPointerGetBlockNumberNoCheck(const ItemPointerData *pointer)
  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
 103 ItemPointerGetBlockNumber(const ItemPointerData *pointer)
 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
 114 ItemPointerGetOffsetNumberNoCheck(const ItemPointerData *pointer)
 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
 124 ItemPointerGetOffsetNumber(const ItemPointerData *pointer)
 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
 135 ItemPointerSet(ItemPointerData *pointer, BlockNumber blockNumber, OffsetNumber offNum)
 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
 147 ItemPointerSetBlockNumber(ItemPointerData *pointer, BlockNumber blockNumber)
 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
 158 ItemPointerSetOffsetNumber(ItemPointerData *pointer, OffsetNumber offsetNumber)
 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
 184 ItemPointerSetInvalid(ItemPointerData *pointer)
 185 {
 186         Assert(PointerIsValid(pointer));
 187         BlockIdSet(&pointer->ip_blkid, InvalidBlockNumber);
 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
 197 ItemPointerIndicatesMovedPartitions(const ItemPointerData *pointer)
 198 {
 199         return
 200                 ItemPointerGetOffsetNumber(pointer) == MovedPartitionsOffsetNumber &&
 201                 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 ItemPointerSetMovedPartitions(ItemPointerData *pointer)
 211 {
 212         ItemPointerSet(pointer, MovedPartitionsBlockNumber, MovedPartitionsOffsetNumber);
 213 }
 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 #endif                                                  /* ITEMPTR_H */