PostgreSQL Source Code  git master
heapam.h
Go to the documentation of this file.
1 /*-------------------------------------------------------------------------
2  *
3  * heapam.h
4  * POSTGRES heap access method definitions.
5  *
6  *
7  * Portions Copyright (c) 1996-2023, PostgreSQL Global Development Group
8  * Portions Copyright (c) 1994, Regents of the University of California
9  *
10  * src/include/access/heapam.h
11  *
12  *-------------------------------------------------------------------------
13  */
14 #ifndef HEAPAM_H
15 #define HEAPAM_H
16 
17 #include "access/relation.h" /* for backward compatibility */
18 #include "access/relscan.h"
19 #include "access/sdir.h"
20 #include "access/skey.h"
21 #include "access/table.h" /* for backward compatibility */
22 #include "access/tableam.h"
23 #include "nodes/lockoptions.h"
24 #include "nodes/primnodes.h"
25 #include "storage/bufpage.h"
26 #include "storage/dsm.h"
27 #include "storage/lockdefs.h"
28 #include "storage/shm_toc.h"
29 #include "utils/relcache.h"
30 #include "utils/snapshot.h"
31 
32 
33 /* "options" flag bits for heap_insert */
34 #define HEAP_INSERT_SKIP_FSM TABLE_INSERT_SKIP_FSM
35 #define HEAP_INSERT_FROZEN TABLE_INSERT_FROZEN
36 #define HEAP_INSERT_NO_LOGICAL TABLE_INSERT_NO_LOGICAL
37 #define HEAP_INSERT_SPECULATIVE 0x0010
38 
40 struct TupleTableSlot;
41 struct VacuumCutoffs;
42 
43 #define MaxLockTupleMode LockTupleExclusive
44 
45 /*
46  * Descriptor for heap table scans.
47  */
48 typedef struct HeapScanDescData
49 {
50  TableScanDescData rs_base; /* AM independent part of the descriptor */
51 
52  /* state set up at initscan time */
53  BlockNumber rs_nblocks; /* total number of blocks in rel */
54  BlockNumber rs_startblock; /* block # to start at */
55  BlockNumber rs_numblocks; /* max number of blocks to scan */
56  /* rs_numblocks is usually InvalidBlockNumber, meaning "scan whole rel" */
57 
58  /* scan current state */
59  bool rs_inited; /* false = scan not init'd yet */
60  BlockNumber rs_cblock; /* current block # in scan, if any */
61  Buffer rs_cbuf; /* current buffer in scan, if any */
62  /* NB: if rs_cbuf is not InvalidBuffer, we hold a pin on that buffer */
63 
64  /* rs_numblocks is usually InvalidBlockNumber, meaning "scan whole rel" */
65  BufferAccessStrategy rs_strategy; /* access strategy for reads */
66 
67  HeapTupleData rs_ctup; /* current tuple in scan, if any */
68 
69  /*
70  * For parallel scans to store page allocation data. NULL when not
71  * performing a parallel scan.
72  */
74 
75  /* these fields only used in page-at-a-time mode and for bitmap scans */
76  int rs_cindex; /* current tuple's index in vistuples */
77  int rs_ntuples; /* number of visible tuples on page */
81 
82 /*
83  * Descriptor for fetches from heap via an index.
84  */
85 typedef struct IndexFetchHeapData
86 {
87  IndexFetchTableData xs_base; /* AM independent part of the descriptor */
88 
89  Buffer xs_cbuf; /* current heap buffer in scan, if any */
90  /* NB: if xs_cbuf is not InvalidBuffer, we hold a pin on that buffer */
92 
93 /* Result codes for HeapTupleSatisfiesVacuum */
94 typedef enum
95 {
96  HEAPTUPLE_DEAD, /* tuple is dead and deletable */
97  HEAPTUPLE_LIVE, /* tuple is live (committed, no deleter) */
98  HEAPTUPLE_RECENTLY_DEAD, /* tuple is dead, but not deletable yet */
99  HEAPTUPLE_INSERT_IN_PROGRESS, /* inserting xact is still in progress */
100  HEAPTUPLE_DELETE_IN_PROGRESS /* deleting xact is still in progress */
102 
103 /*
104  * heap_prepare_freeze_tuple may request that heap_freeze_execute_prepared
105  * check any tuple's to-be-frozen xmin and/or xmax status using pg_xact
106  */
107 #define HEAP_FREEZE_CHECK_XMIN_COMMITTED 0x01
108 #define HEAP_FREEZE_CHECK_XMAX_ABORTED 0x02
109 
110 /* heap_prepare_freeze_tuple state describing how to freeze a tuple */
111 typedef struct HeapTupleFreeze
112 {
113  /* Fields describing how to process tuple */
118 
119  /* xmin/xmax check flags */
121  /* Page offset number for tuple */
124 
125 /*
126  * State used by VACUUM to track the details of freezing all eligible tuples
127  * on a given heap page.
128  *
129  * VACUUM prepares freeze plans for each page via heap_prepare_freeze_tuple
130  * calls (every tuple with storage gets its own call). This page-level freeze
131  * state is updated across each call, which ultimately determines whether or
132  * not freezing the page is required.
133  *
134  * Aside from the basic question of whether or not freezing will go ahead, the
135  * state also tracks the oldest extant XID/MXID in the table as a whole, for
136  * the purposes of advancing relfrozenxid/relminmxid values in pg_class later
137  * on. Each heap_prepare_freeze_tuple call pushes NewRelfrozenXid and/or
138  * NewRelminMxid back as required to avoid unsafe final pg_class values. Any
139  * and all unfrozen XIDs or MXIDs that remain after VACUUM finishes _must_
140  * have values >= the final relfrozenxid/relminmxid values in pg_class. This
141  * includes XIDs that remain as MultiXact members from any tuple's xmax.
142  *
143  * When 'freeze_required' flag isn't set after all tuples are examined, the
144  * final choice on freezing is made by vacuumlazy.c. It can decide to trigger
145  * freezing based on whatever criteria it deems appropriate. However, it is
146  * recommended that vacuumlazy.c avoid early freezing when freezing does not
147  * enable setting the target page all-frozen in the visibility map afterwards.
148  */
149 typedef struct HeapPageFreeze
150 {
151  /* Is heap_prepare_freeze_tuple caller required to freeze page? */
153 
154  /*
155  * "Freeze" NewRelfrozenXid/NewRelminMxid trackers.
156  *
157  * Trackers used when heap_freeze_execute_prepared freezes, or when there
158  * are zero freeze plans for a page. It is always valid for vacuumlazy.c
159  * to freeze any page, by definition. This even includes pages that have
160  * no tuples with storage to consider in the first place. That way the
161  * 'totally_frozen' results from heap_prepare_freeze_tuple can always be
162  * used in the same way, even when no freeze plans need to be executed to
163  * "freeze the page". Only the "freeze" path needs to consider the need
164  * to set pages all-frozen in the visibility map under this scheme.
165  *
166  * When we freeze a page, we generally freeze all XIDs < OldestXmin, only
167  * leaving behind XIDs that are ineligible for freezing, if any. And so
168  * you might wonder why these trackers are necessary at all; why should
169  * _any_ page that VACUUM freezes _ever_ be left with XIDs/MXIDs that
170  * ratchet back the top-level NewRelfrozenXid/NewRelminMxid trackers?
171  *
172  * It is useful to use a definition of "freeze the page" that does not
173  * overspecify how MultiXacts are affected. heap_prepare_freeze_tuple
174  * generally prefers to remove Multis eagerly, but lazy processing is used
175  * in cases where laziness allows VACUUM to avoid allocating a new Multi.
176  * The "freeze the page" trackers enable this flexibility.
177  */
180 
181  /*
182  * "No freeze" NewRelfrozenXid/NewRelminMxid trackers.
183  *
184  * These trackers are maintained in the same way as the trackers used when
185  * VACUUM scans a page that isn't cleanup locked. Both code paths are
186  * based on the same general idea (do less work for this page during the
187  * ongoing VACUUM, at the cost of having to accept older final values).
188  */
191 
193 
194 /* ----------------
195  * function prototypes for heap access method
196  *
197  * heap_create, heap_create_with_catalog, and heap_drop_with_catalog
198  * are declared in catalog/heap.h
199  * ----------------
200  */
201 
202 
203 /*
204  * HeapScanIsValid
205  * True iff the heap scan is valid.
206  */
207 #define HeapScanIsValid(scan) PointerIsValid(scan)
208 
209 extern TableScanDesc heap_beginscan(Relation relation, Snapshot snapshot,
210  int nkeys, ScanKey key,
211  ParallelTableScanDesc parallel_scan,
212  uint32 flags);
213 extern void heap_setscanlimits(TableScanDesc sscan, BlockNumber startBlk,
214  BlockNumber numBlks);
215 extern void heapgetpage(TableScanDesc sscan, BlockNumber block);
216 extern void heap_rescan(TableScanDesc sscan, ScanKey key, bool set_params,
217  bool allow_strat, bool allow_sync, bool allow_pagemode);
218 extern void heap_endscan(TableScanDesc sscan);
219 extern HeapTuple heap_getnext(TableScanDesc sscan, ScanDirection direction);
220 extern bool heap_getnextslot(TableScanDesc sscan,
221  ScanDirection direction, struct TupleTableSlot *slot);
222 extern void heap_set_tidrange(TableScanDesc sscan, ItemPointer mintid,
223  ItemPointer maxtid);
224 extern bool heap_getnextslot_tidrange(TableScanDesc sscan,
225  ScanDirection direction,
226  TupleTableSlot *slot);
227 extern bool heap_fetch(Relation relation, Snapshot snapshot,
228  HeapTuple tuple, Buffer *userbuf, bool keep_buf);
229 extern bool heap_hot_search_buffer(ItemPointer tid, Relation relation,
230  Buffer buffer, Snapshot snapshot, HeapTuple heapTuple,
231  bool *all_dead, bool first_call);
232 
233 extern void heap_get_latest_tid(TableScanDesc sscan, ItemPointer tid);
234 
237 extern void ReleaseBulkInsertStatePin(BulkInsertState bistate);
238 
239 extern void heap_insert(Relation relation, HeapTuple tup, CommandId cid,
240  int options, BulkInsertState bistate);
241 extern void heap_multi_insert(Relation relation, struct TupleTableSlot **slots,
242  int ntuples, CommandId cid, int options,
243  BulkInsertState bistate);
244 extern TM_Result heap_delete(Relation relation, ItemPointer tid,
245  CommandId cid, Snapshot crosscheck, bool wait,
246  struct TM_FailureData *tmfd, bool changingPart);
247 extern void heap_finish_speculative(Relation relation, ItemPointer tid);
248 extern void heap_abort_speculative(Relation relation, ItemPointer tid);
249 extern TM_Result heap_update(Relation relation, ItemPointer otid,
250  HeapTuple newtup,
251  CommandId cid, Snapshot crosscheck, bool wait,
252  struct TM_FailureData *tmfd, LockTupleMode *lockmode);
253 extern TM_Result heap_lock_tuple(Relation relation, HeapTuple tuple,
254  CommandId cid, LockTupleMode mode, LockWaitPolicy wait_policy,
255  bool follow_updates,
256  Buffer *buffer, struct TM_FailureData *tmfd);
257 
258 extern void heap_inplace_update(Relation relation, HeapTuple tuple);
260  const struct VacuumCutoffs *cutoffs,
261  HeapPageFreeze *pagefrz,
262  HeapTupleFreeze *frz, bool *totally_frozen);
263 extern void heap_freeze_execute_prepared(Relation rel, Buffer buffer,
264  TransactionId snapshotConflictHorizon,
265  HeapTupleFreeze *tuples, int ntuples);
266 extern bool heap_freeze_tuple(HeapTupleHeader tuple,
267  TransactionId relfrozenxid, TransactionId relminmxid,
268  TransactionId FreezeLimit, TransactionId MultiXactCutoff);
269 extern bool heap_tuple_should_freeze(HeapTupleHeader tuple,
270  const struct VacuumCutoffs *cutoffs,
271  TransactionId *NoFreezePageRelfrozenXid,
272  MultiXactId *NoFreezePageRelminMxid);
274 
275 extern void simple_heap_insert(Relation relation, HeapTuple tup);
276 extern void simple_heap_delete(Relation relation, ItemPointer tid);
277 extern void simple_heap_update(Relation relation, ItemPointer otid,
278  HeapTuple tup);
279 
281  TM_IndexDeleteOp *delstate);
282 
283 /* in heap/pruneheap.c */
284 struct GlobalVisState;
285 extern void heap_page_prune_opt(Relation relation, Buffer buffer);
286 extern int heap_page_prune(Relation relation, Buffer buffer,
287  struct GlobalVisState *vistest,
288  TransactionId old_snap_xmin,
289  TimestampTz old_snap_ts,
290  int *nnewlpdead,
291  OffsetNumber *off_loc);
292 extern void heap_page_prune_execute(Buffer buffer,
293  OffsetNumber *redirected, int nredirected,
294  OffsetNumber *nowdead, int ndead,
295  OffsetNumber *nowunused, int nunused);
296 extern void heap_get_root_tuples(Page page, OffsetNumber *root_offsets);
297 
298 /* in heap/vacuumlazy.c */
299 struct VacuumParams;
300 extern void heap_vacuum_rel(Relation rel,
301  struct VacuumParams *params, BufferAccessStrategy bstrategy);
302 
303 /* in heap/heapam_visibility.c */
304 extern bool HeapTupleSatisfiesVisibility(HeapTuple htup, Snapshot snapshot,
305  Buffer buffer);
307  Buffer buffer);
309  Buffer buffer);
311  TransactionId *dead_after);
312 extern void HeapTupleSetHintBits(HeapTupleHeader tuple, Buffer buffer,
313  uint16 infomask, TransactionId xid);
315 extern bool HeapTupleIsSurelyDead(HeapTuple htup,
316  struct GlobalVisState *vistest);
317 
318 /*
319  * To avoid leaking too much knowledge about reorderbuffer implementation
320  * details this is implemented in reorderbuffer.c not heapam_visibility.c
321  */
322 struct HTAB;
324  Snapshot snapshot,
325  HeapTuple htup,
326  Buffer buffer,
327  CommandId *cmin, CommandId *cmax);
328 extern void HeapCheckForSerializableConflictOut(bool visible, Relation relation, HeapTuple tuple,
329  Buffer buffer, Snapshot snapshot);
330 
331 #endif /* HEAPAM_H */
uint32 BlockNumber
Definition: block.h:31
int Buffer
Definition: buf.h:23
Pointer Page
Definition: bufpage.h:78
unsigned short uint16
Definition: c.h:489
unsigned int uint32
Definition: c.h:490
TransactionId MultiXactId
Definition: c.h:646
unsigned char uint8
Definition: c.h:488
uint32 CommandId
Definition: c.h:650
uint32 TransactionId
Definition: c.h:636
int64 TimestampTz
Definition: timestamp.h:39
void heap_finish_speculative(Relation relation, ItemPointer tid)
Definition: heapam.c:5765
void heap_insert(Relation relation, HeapTuple tup, CommandId cid, int options, BulkInsertState bistate)
Definition: heapam.c:2028
struct HeapTupleFreeze HeapTupleFreeze
bool heap_fetch(Relation relation, Snapshot snapshot, HeapTuple tuple, Buffer *userbuf, bool keep_buf)
Definition: heapam.c:1557
void HeapTupleSetHintBits(HeapTupleHeader tuple, Buffer buffer, uint16 infomask, TransactionId xid)
bool HeapTupleSatisfiesVisibility(HeapTuple htup, Snapshot snapshot, Buffer buffer)
HTSV_Result HeapTupleSatisfiesVacuumHorizon(HeapTuple htup, Buffer buffer, TransactionId *dead_after)
struct HeapScanDescData * HeapScanDesc
Definition: heapam.h:80
bool HeapTupleIsSurelyDead(HeapTuple htup, struct GlobalVisState *vistest)
void simple_heap_delete(Relation relation, ItemPointer tid)
Definition: heapam.c:3084
int heap_page_prune(Relation relation, Buffer buffer, struct GlobalVisState *vistest, TransactionId old_snap_xmin, TimestampTz old_snap_ts, int *nnewlpdead, OffsetNumber *off_loc)
Definition: pruneheap.c:266
void heap_get_root_tuples(Page page, OffsetNumber *root_offsets)
Definition: pruneheap.c:1111
void heap_vacuum_rel(Relation rel, struct VacuumParams *params, BufferAccessStrategy bstrategy)
Definition: vacuumlazy.c:305
void heap_page_prune_opt(Relation relation, Buffer buffer)
Definition: pruneheap.c:108
HTSV_Result
Definition: heapam.h:95
@ HEAPTUPLE_RECENTLY_DEAD
Definition: heapam.h:98
@ HEAPTUPLE_INSERT_IN_PROGRESS
Definition: heapam.h:99
@ HEAPTUPLE_LIVE
Definition: heapam.h:97
@ HEAPTUPLE_DELETE_IN_PROGRESS
Definition: heapam.h:100
@ HEAPTUPLE_DEAD
Definition: heapam.h:96
void heap_endscan(TableScanDesc sscan)
Definition: heapam.c:1265
void heap_rescan(TableScanDesc sscan, ScanKey key, bool set_params, bool allow_strat, bool allow_sync, bool allow_pagemode)
Definition: heapam.c:1228
void simple_heap_update(Relation relation, ItemPointer otid, HeapTuple tup)
Definition: heapam.c:4168
bool heap_tuple_needs_eventual_freeze(HeapTupleHeader tuple)
Definition: heapam.c:7450
bool ResolveCminCmaxDuringDecoding(struct HTAB *tuplecid_data, Snapshot snapshot, HeapTuple htup, Buffer buffer, CommandId *cmin, CommandId *cmax)
void heap_inplace_update(Relation relation, HeapTuple tuple)
Definition: heapam.c:6005
TM_Result heap_delete(Relation relation, ItemPointer tid, CommandId cid, Snapshot crosscheck, bool wait, struct TM_FailureData *tmfd, bool changingPart)
Definition: heapam.c:2668
bool heap_tuple_should_freeze(HeapTupleHeader tuple, const struct VacuumCutoffs *cutoffs, TransactionId *NoFreezePageRelfrozenXid, MultiXactId *NoFreezePageRelminMxid)
Definition: heapam.c:7505
bool heap_freeze_tuple(HeapTupleHeader tuple, TransactionId relfrozenxid, TransactionId relminmxid, TransactionId FreezeLimit, TransactionId MultiXactCutoff)
Definition: heapam.c:7044
struct HeapPageFreeze HeapPageFreeze
void ReleaseBulkInsertStatePin(BulkInsertState bistate)
Definition: heapam.c:2001
void heap_multi_insert(Relation relation, struct TupleTableSlot **slots, int ntuples, CommandId cid, int options, BulkInsertState bistate)
Definition: heapam.c:2270
HeapTuple heap_getnext(TableScanDesc sscan, ScanDirection direction)
Definition: heapam.c:1298
bool heap_hot_search_buffer(ItemPointer tid, Relation relation, Buffer buffer, Snapshot snapshot, HeapTuple heapTuple, bool *all_dead, bool first_call)
Definition: heapam.c:1678
bool heap_getnextslot_tidrange(TableScanDesc sscan, ScanDirection direction, TupleTableSlot *slot)
Definition: heapam.c:1450
void heap_set_tidrange(TableScanDesc sscan, ItemPointer mintid, ItemPointer maxtid)
Definition: heapam.c:1377
HTSV_Result HeapTupleSatisfiesVacuum(HeapTuple htup, TransactionId OldestXmin, Buffer buffer)
struct HeapScanDescData HeapScanDescData
void heap_abort_speculative(Relation relation, ItemPointer tid)
Definition: heapam.c:5852
TableScanDesc heap_beginscan(Relation relation, Snapshot snapshot, int nkeys, ScanKey key, ParallelTableScanDesc parallel_scan, uint32 flags)
Definition: heapam.c:1143
void heap_freeze_execute_prepared(Relation rel, Buffer buffer, TransactionId snapshotConflictHorizon, HeapTupleFreeze *tuples, int ntuples)
Definition: heapam.c:6794
bool heap_getnextslot(TableScanDesc sscan, ScanDirection direction, struct TupleTableSlot *slot)
Definition: heapam.c:1347
void simple_heap_insert(Relation relation, HeapTuple tup)
Definition: heapam.c:2610
TM_Result heap_update(Relation relation, ItemPointer otid, HeapTuple newtup, CommandId cid, Snapshot crosscheck, bool wait, struct TM_FailureData *tmfd, LockTupleMode *lockmode)
Definition: heapam.c:3130
bool heap_prepare_freeze_tuple(HeapTupleHeader tuple, const struct VacuumCutoffs *cutoffs, HeapPageFreeze *pagefrz, HeapTupleFreeze *frz, bool *totally_frozen)
Definition: heapam.c:6491
TransactionId heap_index_delete_tuples(Relation rel, TM_IndexDeleteOp *delstate)
Definition: heapam.c:7758
bool HeapTupleHeaderIsOnlyLocked(HeapTupleHeader tuple)
TM_Result heap_lock_tuple(Relation relation, HeapTuple tuple, CommandId cid, LockTupleMode mode, LockWaitPolicy wait_policy, bool follow_updates, Buffer *buffer, struct TM_FailureData *tmfd)
Definition: heapam.c:4256
TM_Result HeapTupleSatisfiesUpdate(HeapTuple htup, CommandId curcid, Buffer buffer)
struct BulkInsertStateData * BulkInsertState
Definition: heapam.h:39
void heap_get_latest_tid(TableScanDesc sscan, ItemPointer tid)
Definition: heapam.c:1830
void heap_setscanlimits(TableScanDesc sscan, BlockNumber startBlk, BlockNumber numBlks)
Definition: heapam.c:354
void HeapCheckForSerializableConflictOut(bool visible, Relation relation, HeapTuple tuple, Buffer buffer, Snapshot snapshot)
Definition: heapam.c:10257
void heapgetpage(TableScanDesc sscan, BlockNumber block)
Definition: heapam.c:377
struct IndexFetchHeapData IndexFetchHeapData
void FreeBulkInsertState(BulkInsertState)
Definition: heapam.c:1989
void heap_page_prune_execute(Buffer buffer, OffsetNumber *redirected, int nredirected, OffsetNumber *nowdead, int ndead, OffsetNumber *nowunused, int nunused)
Definition: pruneheap.c:912
BulkInsertState GetBulkInsertState(void)
Definition: heapam.c:1975
#define MaxHeapTuplesPerPage
Definition: htup_details.h:572
LockWaitPolicy
Definition: lockoptions.h:37
LockTupleMode
Definition: lockoptions.h:50
uint16 OffsetNumber
Definition: off.h:24
static PgChecksumMode mode
Definition: pg_checksums.c:65
ScanDirection
Definition: sdir.h:23
static HTAB * tuplecid_data
Definition: snapmgr.c:117
Definition: dynahash.c:220
MultiXactId NoFreezePageRelminMxid
Definition: heapam.h:190
TransactionId FreezePageRelfrozenXid
Definition: heapam.h:178
bool freeze_required
Definition: heapam.h:152
MultiXactId FreezePageRelminMxid
Definition: heapam.h:179
TransactionId NoFreezePageRelfrozenXid
Definition: heapam.h:189
int rs_ntuples
Definition: heapam.h:77
BufferAccessStrategy rs_strategy
Definition: heapam.h:65
bool rs_inited
Definition: heapam.h:59
Buffer rs_cbuf
Definition: heapam.h:61
ParallelBlockTableScanWorkerData * rs_parallelworkerdata
Definition: heapam.h:73
BlockNumber rs_startblock
Definition: heapam.h:54
HeapTupleData rs_ctup
Definition: heapam.h:67
OffsetNumber rs_vistuples[MaxHeapTuplesPerPage]
Definition: heapam.h:78
BlockNumber rs_numblocks
Definition: heapam.h:55
BlockNumber rs_nblocks
Definition: heapam.h:53
BlockNumber rs_cblock
Definition: heapam.h:60
TableScanDescData rs_base
Definition: heapam.h:50
uint8 frzflags
Definition: heapam.h:117
uint16 t_infomask2
Definition: heapam.h:115
TransactionId xmax
Definition: heapam.h:114
OffsetNumber offset
Definition: heapam.h:122
uint8 checkflags
Definition: heapam.h:120
uint16 t_infomask
Definition: heapam.h:116
Buffer xs_cbuf
Definition: heapam.h:89
IndexFetchTableData xs_base
Definition: heapam.h:87
TM_Result
Definition: tableam.h:72