PostgreSQL Source Code  git master
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros
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-2017, 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/sdir.h"
18 #include "access/skey.h"
19 #include "nodes/lockoptions.h"
20 #include "nodes/primnodes.h"
21 #include "storage/bufpage.h"
22 #include "storage/lockdefs.h"
23 #include "utils/relcache.h"
24 #include "utils/snapshot.h"
25 
26 
27 /* "options" flag bits for heap_insert */
28 #define HEAP_INSERT_SKIP_WAL 0x0001
29 #define HEAP_INSERT_SKIP_FSM 0x0002
30 #define HEAP_INSERT_FROZEN 0x0004
31 #define HEAP_INSERT_SPECULATIVE 0x0008
32 
34 
35 /*
36  * Possible lock modes for a tuple.
37  */
38 typedef enum LockTupleMode
39 {
40  /* SELECT FOR KEY SHARE */
42  /* SELECT FOR SHARE */
44  /* SELECT FOR NO KEY UPDATE, and UPDATEs that don't modify key columns */
46  /* SELECT FOR UPDATE, UPDATEs that modify key columns, and DELETE */
49 
50 #define MaxLockTupleMode LockTupleExclusive
51 
52 /*
53  * When heap_update, heap_delete, or heap_lock_tuple fail because the target
54  * tuple is already outdated, they fill in this struct to provide information
55  * to the caller about what happened.
56  * ctid is the target's ctid link: it is the same as the target's TID if the
57  * target was deleted, or the location of the replacement tuple if the target
58  * was updated.
59  * xmax is the outdating transaction's XID. If the caller wants to visit the
60  * replacement tuple, it must check that this matches before believing the
61  * replacement is really a match.
62  * cmax is the outdating command's CID, but only when the failure code is
63  * HeapTupleSelfUpdated (i.e., something in the current transaction outdated
64  * the tuple); otherwise cmax is zero. (We make this restriction because
65  * HeapTupleHeaderGetCmax doesn't work for tuples outdated in other
66  * transactions.)
67  */
68 typedef struct HeapUpdateFailureData
69 {
74 
75 
76 /* ----------------
77  * function prototypes for heap access method
78  *
79  * heap_create, heap_create_with_catalog, and heap_drop_with_catalog
80  * are declared in catalog/heap.h
81  * ----------------
82  */
83 
84 /* in heap/heapam.c */
85 extern Relation relation_open(Oid relationId, LOCKMODE lockmode);
86 extern Relation try_relation_open(Oid relationId, LOCKMODE lockmode);
87 extern Relation relation_openrv(const RangeVar *relation, LOCKMODE lockmode);
88 extern Relation relation_openrv_extended(const RangeVar *relation,
89  LOCKMODE lockmode, bool missing_ok);
90 extern void relation_close(Relation relation, LOCKMODE lockmode);
91 
92 extern Relation heap_open(Oid relationId, LOCKMODE lockmode);
93 extern Relation heap_openrv(const RangeVar *relation, LOCKMODE lockmode);
94 extern Relation heap_openrv_extended(const RangeVar *relation,
95  LOCKMODE lockmode, bool missing_ok);
96 
97 #define heap_close(r,l) relation_close(r,l)
98 
99 /* struct definitions appear in relscan.h */
102 
103 /*
104  * HeapScanIsValid
105  * True iff the heap scan is valid.
106  */
107 #define HeapScanIsValid(scan) PointerIsValid(scan)
108 
109 extern HeapScanDesc heap_beginscan(Relation relation, Snapshot snapshot,
110  int nkeys, ScanKey key);
111 extern HeapScanDesc heap_beginscan_catalog(Relation relation, int nkeys,
112  ScanKey key);
113 extern HeapScanDesc heap_beginscan_strat(Relation relation, Snapshot snapshot,
114  int nkeys, ScanKey key,
115  bool allow_strat, bool allow_sync);
116 extern HeapScanDesc heap_beginscan_bm(Relation relation, Snapshot snapshot,
117  int nkeys, ScanKey key);
118 extern HeapScanDesc heap_beginscan_sampling(Relation relation,
119  Snapshot snapshot, int nkeys, ScanKey key,
120  bool allow_strat, bool allow_sync, bool allow_pagemode);
121 extern void heap_setscanlimits(HeapScanDesc scan, BlockNumber startBlk,
122  BlockNumber endBlk);
123 extern void heapgetpage(HeapScanDesc scan, BlockNumber page);
124 extern void heap_rescan(HeapScanDesc scan, ScanKey key);
125 extern void heap_rescan_set_params(HeapScanDesc scan, ScanKey key,
126  bool allow_strat, bool allow_sync, bool allow_pagemode);
127 extern void heap_endscan(HeapScanDesc scan);
128 extern HeapTuple heap_getnext(HeapScanDesc scan, ScanDirection direction);
129 
130 extern Size heap_parallelscan_estimate(Snapshot snapshot);
131 extern void heap_parallelscan_initialize(ParallelHeapScanDesc target,
132  Relation relation, Snapshot snapshot);
133 extern HeapScanDesc heap_beginscan_parallel(Relation, ParallelHeapScanDesc);
134 
135 extern bool heap_fetch(Relation relation, Snapshot snapshot,
136  HeapTuple tuple, Buffer *userbuf, bool keep_buf,
137  Relation stats_relation);
138 extern bool heap_hot_search_buffer(ItemPointer tid, Relation relation,
139  Buffer buffer, Snapshot snapshot, HeapTuple heapTuple,
140  bool *all_dead, bool first_call);
141 extern bool heap_hot_search(ItemPointer tid, Relation relation,
142  Snapshot snapshot, bool *all_dead);
143 
144 extern void heap_get_latest_tid(Relation relation, Snapshot snapshot,
145  ItemPointer tid);
146 extern void setLastTid(const ItemPointer tid);
147 
148 extern BulkInsertState GetBulkInsertState(void);
149 extern void FreeBulkInsertState(BulkInsertState);
150 extern void ReleaseBulkInsertStatePin(BulkInsertState bistate);
151 
152 extern Oid heap_insert(Relation relation, HeapTuple tup, CommandId cid,
153  int options, BulkInsertState bistate);
154 extern void heap_multi_insert(Relation relation, HeapTuple *tuples, int ntuples,
155  CommandId cid, int options, BulkInsertState bistate);
156 extern HTSU_Result heap_delete(Relation relation, ItemPointer tid,
157  CommandId cid, Snapshot crosscheck, bool wait,
158  HeapUpdateFailureData *hufd);
159 extern void heap_finish_speculative(Relation relation, HeapTuple tuple);
160 extern void heap_abort_speculative(Relation relation, HeapTuple tuple);
161 extern HTSU_Result heap_update(Relation relation, ItemPointer otid,
162  HeapTuple newtup,
163  CommandId cid, Snapshot crosscheck, bool wait,
164  HeapUpdateFailureData *hufd, LockTupleMode *lockmode);
165 extern HTSU_Result heap_lock_tuple(Relation relation, HeapTuple tuple,
166  CommandId cid, LockTupleMode mode, LockWaitPolicy wait_policy,
167  bool follow_update,
169 extern void heap_inplace_update(Relation relation, HeapTuple tuple);
170 extern bool heap_freeze_tuple(HeapTupleHeader tuple, TransactionId cutoff_xid,
171  TransactionId cutoff_multi);
172 extern bool heap_tuple_needs_freeze(HeapTupleHeader tuple, TransactionId cutoff_xid,
173  MultiXactId cutoff_multi, Buffer buf);
175 
176 extern Oid 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 void heap_sync(Relation relation);
182 extern void heap_update_snapshot(HeapScanDesc scan, Snapshot snapshot);
183 
184 /* in heap/pruneheap.c */
185 extern void heap_page_prune_opt(Relation relation, Buffer buffer);
186 extern int heap_page_prune(Relation relation, Buffer buffer,
188  bool report_stats, TransactionId *latestRemovedXid);
190  OffsetNumber *redirected, int nredirected,
191  OffsetNumber *nowdead, int ndead,
192  OffsetNumber *nowunused, int nunused);
193 extern void heap_get_root_tuples(Page page, OffsetNumber *root_offsets);
194 
195 /* in heap/syncscan.c */
196 extern void ss_report_location(Relation rel, BlockNumber location);
197 extern BlockNumber ss_get_location(Relation rel, BlockNumber relnblocks);
198 extern void SyncScanShmemInit(void);
199 extern Size SyncScanShmemSize(void);
200 
201 #endif /* HEAPAM_H */
void heapgetpage(HeapScanDesc scan, BlockNumber page)
Definition: heapam.c:345
uint32 CommandId
Definition: c.h:411
struct HeapUpdateFailureData HeapUpdateFailureData
void heap_endscan(HeapScanDesc scan)
Definition: heapam.c:1578
void SyncScanShmemInit(void)
Definition: syncscan.c:135
HeapScanDesc heap_beginscan(Relation relation, Snapshot snapshot, int nkeys, ScanKey key)
Definition: heapam.c:1391
void heap_sync(Relation relation)
Definition: heapam.c:9084
uint32 TransactionId
Definition: c.h:397
Relation relation_open(Oid relationId, LOCKMODE lockmode)
Definition: heapam.c:1114
int LOCKMODE
Definition: lockdefs.h:26
Size heap_parallelscan_estimate(Snapshot snapshot)
Definition: heapam.c:1613
void ReleaseBulkInsertStatePin(BulkInsertState bistate)
Definition: heapam.c:2345
bool heap_tuple_needs_eventual_freeze(HeapTupleHeader tuple)
Definition: heapam.c:7148
uint32 BlockNumber
Definition: block.h:31
unsigned int Oid
Definition: postgres_ext.h:31
void heap_rescan(HeapScanDesc scan, ScanKey key)
Definition: heapam.c:1515
bool heap_fetch(Relation relation, Snapshot snapshot, HeapTuple tuple, Buffer *userbuf, bool keep_buf, Relation stats_relation)
Definition: heapam.c:1862
HeapScanDesc heap_beginscan_catalog(Relation relation, int nkeys, ScanKey key)
Definition: heapam.c:1399
void heap_abort_speculative(Relation relation, HeapTuple tuple)
Definition: heapam.c:6054
struct HeapScanDescData * HeapScanDesc
Definition: heapam.h:100
void heap_finish_speculative(Relation relation, HeapTuple tuple)
Definition: heapam.c:5963
void heap_get_root_tuples(Page page, OffsetNumber *root_offsets)
Definition: pruneheap.c:743
uint16 OffsetNumber
Definition: off.h:24
void heap_setscanlimits(HeapScanDesc scan, BlockNumber startBlk, BlockNumber endBlk)
Definition: heapam.c:325
HTSU_Result heap_delete(Relation relation, ItemPointer tid, CommandId cid, Snapshot crosscheck, bool wait, HeapUpdateFailureData *hufd)
Definition: heapam.c:3011
bool heap_hot_search(ItemPointer tid, Relation relation, Snapshot snapshot, bool *all_dead)
Definition: heapam.c:2139
void simple_heap_delete(Relation relation, ItemPointer tid)
Definition: heapam.c:3398
LockTupleMode
Definition: heapam.h:38
Relation relation_openrv_extended(const RangeVar *relation, LOCKMODE lockmode, bool missing_ok)
Definition: heapam.c:1227
BulkInsertState GetBulkInsertState(void)
Definition: heapam.c:2319
HeapTuple heap_getnext(HeapScanDesc scan, ScanDirection direction)
Definition: heapam.c:1794
Relation heap_openrv(const RangeVar *relation, LOCKMODE lockmode)
Definition: heapam.c:1312
int heap_page_prune(Relation relation, Buffer buffer, TransactionId OldestXmin, bool report_stats, TransactionId *latestRemovedXid)
Definition: pruneheap.c:181
bool heap_freeze_tuple(HeapTupleHeader tuple, TransactionId cutoff_xid, TransactionId cutoff_multi)
Definition: heapam.c:6769
static char * buf
Definition: pg_test_fsync.c:66
HTSU_Result heap_lock_tuple(Relation relation, HeapTuple tuple, CommandId cid, LockTupleMode mode, LockWaitPolicy wait_policy, bool follow_update, Buffer *buffer, HeapUpdateFailureData *hufd)
Definition: heapam.c:4540
void heap_parallelscan_initialize(ParallelHeapScanDesc target, Relation relation, Snapshot snapshot)
Definition: heapam.c:1628
ScanDirection
Definition: sdir.h:22
CommandId cmax
Definition: heapam.h:72
Oid heap_insert(Relation relation, HeapTuple tup, CommandId cid, int options, BulkInsertState bistate)
Definition: heapam.c:2396
HTSU_Result
Definition: snapshot.h:119
static TransactionId OldestXmin
Definition: vacuumlazy.c:138
void setLastTid(const ItemPointer tid)
Definition: tid.c:254
HeapScanDesc heap_beginscan_bm(Relation relation, Snapshot snapshot, int nkeys, ScanKey key)
Definition: heapam.c:1419
void heap_update_snapshot(HeapScanDesc scan, Snapshot snapshot)
Definition: heapam.c:1760
bool heap_hot_search_buffer(ItemPointer tid, Relation relation, Buffer buffer, Snapshot snapshot, HeapTuple heapTuple, bool *all_dead, bool first_call)
Definition: heapam.c:1997
TransactionId xmax
Definition: heapam.h:71
struct ParallelHeapScanDescData * ParallelHeapScanDesc
Definition: heapam.h:101
Relation relation_openrv(const RangeVar *relation, LOCKMODE lockmode)
Definition: heapam.c:1192
HTSU_Result heap_update(Relation relation, ItemPointer otid, HeapTuple newtup, CommandId cid, Snapshot crosscheck, bool wait, HeapUpdateFailureData *hufd, LockTupleMode *lockmode)
Definition: heapam.c:3462
Size SyncScanShmemSize(void)
Definition: syncscan.c:126
TransactionId MultiXactId
Definition: c.h:407
void ss_report_location(Relation rel, BlockNumber location)
Definition: syncscan.c:288
WalTimeSample buffer[LAG_TRACKER_BUFFER_SIZE]
Definition: walsender.c:214
size_t Size
Definition: c.h:356
Relation heap_openrv_extended(const RangeVar *relation, LOCKMODE lockmode, bool missing_ok)
Definition: heapam.c:1341
Oid simple_heap_insert(Relation relation, HeapTuple tup)
Definition: heapam.c:2939
struct BulkInsertStateData * BulkInsertState
Definition: heapam.h:33
bool heap_tuple_needs_freeze(HeapTupleHeader tuple, TransactionId cutoff_xid, MultiXactId cutoff_multi, Buffer buf)
Definition: heapam.c:7201
Relation heap_open(Oid relationId, LOCKMODE lockmode)
Definition: heapam.c:1284
void FreeBulkInsertState(BulkInsertState)
Definition: heapam.c:2333
void heap_get_latest_tid(Relation relation, Snapshot snapshot, ItemPointer tid)
Definition: heapam.c:2167
void relation_close(Relation relation, LOCKMODE lockmode)
Definition: heapam.c:1260
HeapScanDesc heap_beginscan_parallel(Relation, ParallelHeapScanDesc)
Definition: heapam.c:1650
void heap_rescan_set_params(HeapScanDesc scan, ScanKey key, bool allow_strat, bool allow_sync, bool allow_pagemode)
Definition: heapam.c:1559
void heap_page_prune_execute(Buffer buffer, OffsetNumber *redirected, int nredirected, OffsetNumber *nowdead, int ndead, OffsetNumber *nowunused, int nunused)
Definition: pruneheap.c:679
void heap_inplace_update(Relation relation, HeapTuple tuple)
Definition: heapam.c:6195
Relation try_relation_open(Oid relationId, LOCKMODE lockmode)
Definition: heapam.c:1147
void simple_heap_update(Relation relation, ItemPointer otid, HeapTuple tup)
Definition: heapam.c:4451
ItemPointerData ctid
Definition: heapam.h:70
HeapScanDesc heap_beginscan_strat(Relation relation, Snapshot snapshot, int nkeys, ScanKey key, bool allow_strat, bool allow_sync)
Definition: heapam.c:1409
int Buffer
Definition: buf.h:23
void heap_multi_insert(Relation relation, HeapTuple *tuples, int ntuples, CommandId cid, int options, BulkInsertState bistate)
Definition: heapam.c:2658
LockWaitPolicy
Definition: lockoptions.h:36
Pointer Page
Definition: bufpage.h:74
HeapScanDesc heap_beginscan_sampling(Relation relation, Snapshot snapshot, int nkeys, ScanKey key, bool allow_strat, bool allow_sync, bool allow_pagemode)
Definition: heapam.c:1427
BlockNumber ss_get_location(Relation rel, BlockNumber relnblocks)
Definition: syncscan.c:253
void heap_page_prune_opt(Relation relation, Buffer buffer)
Definition: pruneheap.c:74