src/include/access/heapam.h

   1 /*-------------------------------------------------------------------------
   2  *
   3  * heapam.h
   4  *        POSTGRES heap access method 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/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
  39 typedef struct BulkInsertStateData *BulkInsertState;
  40 struct TupleTableSlot;
  41
  42 #define MaxLockTupleMode        LockTupleExclusive
  43
  44 /*
  45  * Descriptor for heap table scans.
  46  */
  47 typedef struct HeapScanDescData
  48 {
  49         TableScanDescData rs_base;      /* AM independent part of the descriptor */
  50
  51         /* state set up at initscan time */
  52         BlockNumber rs_nblocks;         /* total number of blocks in rel */
  53         BlockNumber rs_startblock;      /* block # to start at */
  54         BlockNumber rs_numblocks;       /* max number of blocks to scan */
  55         /* rs_numblocks is usually InvalidBlockNumber, meaning "scan whole rel" */
  56
  57         /* scan current state */
  58         bool            rs_inited;              /* false = scan not init'd yet */
  59         BlockNumber rs_cblock;          /* current block # in scan, if any */
  60         Buffer          rs_cbuf;                /* current buffer in scan, if any */
  61         /* NB: if rs_cbuf is not InvalidBuffer, we hold a pin on that buffer */
  62
  63         /* rs_numblocks is usually InvalidBlockNumber, meaning "scan whole rel" */
  64         BufferAccessStrategy rs_strategy;       /* access strategy for reads */
  65
  66         HeapTupleData rs_ctup;          /* current tuple in scan, if any */
  67
  68         /*
  69          * For parallel scans to store page allocation data.  NULL when not
  70          * performing a parallel scan.
  71          */
  72         ParallelBlockTableScanWorkerData *rs_parallelworkerdata;
  73
  74         /* these fields only used in page-at-a-time mode and for bitmap scans */
  75         int                     rs_cindex;              /* current tuple's index in vistuples */
  76         int                     rs_ntuples;             /* number of visible tuples on page */
  77         OffsetNumber rs_vistuples[MaxHeapTuplesPerPage];        /* their offsets */
  78 }                       HeapScanDescData;
  79 typedef struct HeapScanDescData *HeapScanDesc;
  80
  81 /*
  82  * Descriptor for fetches from heap via an index.
  83  */
  84 typedef struct IndexFetchHeapData
  85 {
  86         IndexFetchTableData xs_base;    /* AM independent part of the descriptor */
  87
  88         Buffer          xs_cbuf;                /* current heap buffer in scan, if any */
  89         /* NB: if xs_cbuf is not InvalidBuffer, we hold a pin on that buffer */
  90 } IndexFetchHeapData;
  91
  92 /* Result codes for HeapTupleSatisfiesVacuum */
  93 typedef enum
  94 {
  95         HEAPTUPLE_DEAD,                         /* tuple is dead and deletable */
  96         HEAPTUPLE_LIVE,                         /* tuple is live (committed, no deleter) */
  97         HEAPTUPLE_RECENTLY_DEAD,        /* tuple is dead, but not deletable yet */
  98         HEAPTUPLE_INSERT_IN_PROGRESS,   /* inserting xact is still in progress */
  99         HEAPTUPLE_DELETE_IN_PROGRESS    /* deleting xact is still in progress */
 100 } HTSV_Result;
 101
 102 /* ----------------
 103  *              function prototypes for heap access method
 104  *
 105  * heap_create, heap_create_with_catalog, and heap_drop_with_catalog
 106  * are declared in catalog/heap.h
 107  * ----------------
 108  */
 109
 110
 111 /*
 112  * HeapScanIsValid
 113  *              True iff the heap scan is valid.
 114  */
 115 #define HeapScanIsValid(scan) PointerIsValid(scan)
 116
 117 extern TableScanDesc heap_beginscan(Relation relation, Snapshot snapshot,
 118                                                                         int nkeys, ScanKey key,
 119                                                                         ParallelTableScanDesc parallel_scan,
 120                                                                         uint32 flags);
 121 extern void heap_setscanlimits(TableScanDesc sscan, BlockNumber startBlk,
 122                                                            BlockNumber numBlks);
 123 extern void heapgetpage(TableScanDesc sscan, BlockNumber page);
 124 extern void heap_rescan(TableScanDesc sscan, ScanKey key, bool set_params,
 125                                                 bool allow_strat, bool allow_sync, bool allow_pagemode);
 126 extern void heap_endscan(TableScanDesc sscan);
 127 extern HeapTuple heap_getnext(TableScanDesc sscan, ScanDirection direction);
 128 extern bool heap_getnextslot(TableScanDesc sscan,
 129                                                          ScanDirection direction, struct TupleTableSlot *slot);
 130 extern void heap_set_tidrange(TableScanDesc sscan, ItemPointer mintid,
 131                                                           ItemPointer maxtid);
 132 extern bool heap_getnextslot_tidrange(TableScanDesc sscan,
 133                                                                           ScanDirection direction,
 134                                                                           TupleTableSlot *slot);
 135 extern bool heap_fetch(Relation relation, Snapshot snapshot,
 136                                            HeapTuple tuple, Buffer *userbuf, bool keep_buf);
 137 extern bool heap_hot_search_buffer(ItemPointer tid, Relation relation,
 138                                                                    Buffer buffer, Snapshot snapshot, HeapTuple heapTuple,
 139                                                                    bool *all_dead, bool first_call);
 140
 141 extern void heap_get_latest_tid(TableScanDesc sscan, ItemPointer tid);
 142
 143 extern BulkInsertState GetBulkInsertState(void);
 144 extern void FreeBulkInsertState(BulkInsertState);
 145 extern void ReleaseBulkInsertStatePin(BulkInsertState bistate);
 146
 147 extern void heap_insert(Relation relation, HeapTuple tup, CommandId cid,
 148                                                 int options, BulkInsertState bistate);
 149 extern void heap_multi_insert(Relation relation, struct TupleTableSlot **slots,
 150                                                           int ntuples, CommandId cid, int options,
 151                                                           BulkInsertState bistate);
 152 extern TM_Result heap_delete(Relation relation, ItemPointer tid,
 153                                                          CommandId cid, Snapshot crosscheck, bool wait,
 154                                                          struct TM_FailureData *tmfd, bool changingPart);
 155 extern void heap_finish_speculative(Relation relation, ItemPointer tid);
 156 extern void heap_abort_speculative(Relation relation, ItemPointer tid);
 157 extern TM_Result heap_update(Relation relation, ItemPointer otid,
 158                                                          HeapTuple newtup,
 159                                                          CommandId cid, Snapshot crosscheck, bool wait,
 160                                                          struct TM_FailureData *tmfd, LockTupleMode *lockmode);
 161 extern TM_Result heap_lock_tuple(Relation relation, HeapTuple tuple,
 162                                                                  CommandId cid, LockTupleMode mode, LockWaitPolicy wait_policy,
 163                                                                  bool follow_updates,
 164                                                                  Buffer *buffer, struct TM_FailureData *tmfd);
 165
 166 extern void heap_inplace_update(Relation relation, HeapTuple tuple);
 167 extern bool heap_freeze_tuple(HeapTupleHeader tuple,
 168                                                           TransactionId relfrozenxid, TransactionId relminmxid,
 169                                                           TransactionId cutoff_xid, TransactionId cutoff_multi);
 170 extern bool heap_tuple_would_freeze(HeapTupleHeader tuple, TransactionId cutoff_xid,
 171                                                                         MultiXactId cutoff_multi,
 172                                                                         TransactionId *relfrozenxid_out,
 173                                                                         MultiXactId *relminmxid_out);
 174 extern bool heap_tuple_needs_eventual_freeze(HeapTupleHeader tuple);
 175
 176 extern void simple_heap_insert(Relation relation, HeapTuple tup);
 177 extern void simple_heap_delete(Relation relation, ItemPointer tid);
 178 extern void simple_heap_update(Relation relation, ItemPointer otid,
 179                                                            HeapTuple tup);
 180
 181 extern TransactionId heap_index_delete_tuples(Relation rel,
 182                                                                                           TM_IndexDeleteOp *delstate);
 183
 184 /* in heap/pruneheap.c */
 185 struct GlobalVisState;
 186 extern void heap_page_prune_opt(Relation relation, Buffer buffer);
 187 extern int      heap_page_prune(Relation relation, Buffer buffer,
 188                                                         struct GlobalVisState *vistest,
 189                                                         TransactionId old_snap_xmin,
 190                                                         TimestampTz old_snap_ts,
 191                                                         int *nnewlpdead,
 192                                                         OffsetNumber *off_loc);
 193 extern void heap_page_prune_execute(Buffer buffer,
 194                                                                         OffsetNumber *redirected, int nredirected,
 195                                                                         OffsetNumber *nowdead, int ndead,
 196                                                                         OffsetNumber *nowunused, int nunused);
 197 extern void heap_get_root_tuples(Page page, OffsetNumber *root_offsets);
 198
 199 /* in heap/vacuumlazy.c */
 200 struct VacuumParams;
 201 extern void heap_vacuum_rel(Relation rel,
 202                                                         struct VacuumParams *params, BufferAccessStrategy bstrategy);
 203
 204 /* in heap/heapam_visibility.c */
 205 extern bool HeapTupleSatisfiesVisibility(HeapTuple htup, Snapshot snapshot,
 206                                                                                  Buffer buffer);
 207 extern TM_Result HeapTupleSatisfiesUpdate(HeapTuple htup, CommandId curcid,
 208                                                                                   Buffer buffer);
 209 extern HTSV_Result HeapTupleSatisfiesVacuum(HeapTuple htup, TransactionId OldestXmin,
 210                                                                                         Buffer buffer);
 211 extern HTSV_Result HeapTupleSatisfiesVacuumHorizon(HeapTuple htup, Buffer buffer,
 212                                                                                                    TransactionId *dead_after);
 213 extern void HeapTupleSetHintBits(HeapTupleHeader tuple, Buffer buffer,
 214                                                                  uint16 infomask, TransactionId xid);
 215 extern bool HeapTupleHeaderIsOnlyLocked(HeapTupleHeader tuple);
 216 extern bool XidInMVCCSnapshot(TransactionId xid, Snapshot snapshot);
 217 extern bool HeapTupleIsSurelyDead(HeapTuple htup,
 218                                                                   struct GlobalVisState *vistest);
 219
 220 /*
 221  * To avoid leaking too much knowledge about reorderbuffer implementation
 222  * details this is implemented in reorderbuffer.c not heapam_visibility.c
 223  */
 224 struct HTAB;
 225 extern bool ResolveCminCmaxDuringDecoding(struct HTAB *tuplecid_data,
 226                                                                                   Snapshot snapshot,
 227                                                                                   HeapTuple htup,
 228                                                                                   Buffer buffer,
 229                                                                                   CommandId *cmin, CommandId *cmax);
 230 extern void HeapCheckForSerializableConflictOut(bool visible, Relation relation, HeapTuple tuple,
 231                                                                                                 Buffer buffer, Snapshot snapshot);
 232
 233 #endif                                                  /* HEAPAM_H */