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 void heap_parallelscan_reinitialize(ParallelHeapScanDesc parallel_scan);
134 extern HeapScanDesc heap_beginscan_parallel(Relation, ParallelHeapScanDesc);
135 
136 extern bool heap_fetch(Relation relation, Snapshot snapshot,
137  HeapTuple tuple, Buffer *userbuf, bool keep_buf,
138  Relation stats_relation);
139 extern bool heap_hot_search_buffer(ItemPointer tid, Relation relation,
140  Buffer buffer, Snapshot snapshot, HeapTuple heapTuple,
141  bool *all_dead, bool first_call);
142 extern bool heap_hot_search(ItemPointer tid, Relation relation,
143  Snapshot snapshot, bool *all_dead);
144 
145 extern void heap_get_latest_tid(Relation relation, Snapshot snapshot,
146  ItemPointer tid);
147 extern void setLastTid(const ItemPointer tid);
148 
149 extern BulkInsertState GetBulkInsertState(void);
150 extern void FreeBulkInsertState(BulkInsertState);
151 extern void ReleaseBulkInsertStatePin(BulkInsertState bistate);
152 
153 extern Oid heap_insert(Relation relation, HeapTuple tup, CommandId cid,
154  int options, BulkInsertState bistate);
155 extern void heap_multi_insert(Relation relation, HeapTuple *tuples, int ntuples,
156  CommandId cid, int options, BulkInsertState bistate);
157 extern HTSU_Result heap_delete(Relation relation, ItemPointer tid,
158  CommandId cid, Snapshot crosscheck, bool wait,
159  HeapUpdateFailureData *hufd);
160 extern void heap_finish_speculative(Relation relation, HeapTuple tuple);
161 extern void heap_abort_speculative(Relation relation, HeapTuple tuple);
162 extern HTSU_Result heap_update(Relation relation, ItemPointer otid,
163  HeapTuple newtup,
164  CommandId cid, Snapshot crosscheck, bool wait,
165  HeapUpdateFailureData *hufd, LockTupleMode *lockmode);
166 extern HTSU_Result heap_lock_tuple(Relation relation, HeapTuple tuple,
167  CommandId cid, LockTupleMode mode, LockWaitPolicy wait_policy,
168  bool follow_update,
170 extern void heap_inplace_update(Relation relation, HeapTuple tuple);
171 extern bool heap_freeze_tuple(HeapTupleHeader tuple, TransactionId cutoff_xid,
172  TransactionId cutoff_multi);
173 extern bool heap_tuple_needs_freeze(HeapTupleHeader tuple, TransactionId cutoff_xid,
174  MultiXactId cutoff_multi, Buffer buf);
176 
177 extern Oid simple_heap_insert(Relation relation, HeapTuple tup);
178 extern void simple_heap_delete(Relation relation, ItemPointer tid);
179 extern void simple_heap_update(Relation relation, ItemPointer otid,
180  HeapTuple tup);
181 
182 extern void heap_sync(Relation relation);
183 extern void heap_update_snapshot(HeapScanDesc scan, Snapshot snapshot);
184 
185 /* in heap/pruneheap.c */
186 extern void heap_page_prune_opt(Relation relation, Buffer buffer);
187 extern int heap_page_prune(Relation relation, Buffer buffer,
189  bool report_stats, TransactionId *latestRemovedXid);
191  OffsetNumber *redirected, int nredirected,
192  OffsetNumber *nowdead, int ndead,
193  OffsetNumber *nowunused, int nunused);
194 extern void heap_get_root_tuples(Page page, OffsetNumber *root_offsets);
195 
196 /* in heap/syncscan.c */
197 extern void ss_report_location(Relation rel, BlockNumber location);
198 extern BlockNumber ss_get_location(Relation rel, BlockNumber relnblocks);
199 extern void SyncScanShmemInit(void);
200 extern Size SyncScanShmemSize(void);
201 
202 #endif /* HEAPAM_H */
void heapgetpage(HeapScanDesc scan, BlockNumber page)
Definition: heapam.c:347
uint32 CommandId
Definition: c.h:405
struct HeapUpdateFailureData HeapUpdateFailureData
void heap_endscan(HeapScanDesc scan)
Definition: heapam.c:1565
void SyncScanShmemInit(void)
Definition: syncscan.c:135
HeapScanDesc heap_beginscan(Relation relation, Snapshot snapshot, int nkeys, ScanKey key)
Definition: heapam.c:1397
void heap_sync(Relation relation)
Definition: heapam.c:9135
uint32 TransactionId
Definition: c.h:391
Relation relation_open(Oid relationId, LOCKMODE lockmode)
Definition: heapam.c:1120
int LOCKMODE
Definition: lockdefs.h:26
Size heap_parallelscan_estimate(Snapshot snapshot)
Definition: heapam.c:1600
void heap_parallelscan_reinitialize(ParallelHeapScanDesc parallel_scan)
Definition: heapam.c:1638
void ReleaseBulkInsertStatePin(BulkInsertState bistate)
Definition: heapam.c:2362
bool heap_tuple_needs_eventual_freeze(HeapTupleHeader tuple)
Definition: heapam.c:7199
uint32 BlockNumber
Definition: block.h:31
unsigned int Oid
Definition: postgres_ext.h:31
void heap_rescan(HeapScanDesc scan, ScanKey key)
Definition: heapam.c:1521
bool heap_fetch(Relation relation, Snapshot snapshot, HeapTuple tuple, Buffer *userbuf, bool keep_buf, Relation stats_relation)
Definition: heapam.c:1876
HeapScanDesc heap_beginscan_catalog(Relation relation, int nkeys, ScanKey key)
Definition: heapam.c:1405
void heap_abort_speculative(Relation relation, HeapTuple tuple)
Definition: heapam.c:6105
struct HeapScanDescData * HeapScanDesc
Definition: heapam.h:100
void heap_finish_speculative(Relation relation, HeapTuple tuple)
Definition: heapam.c:6014
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:327
HTSU_Result heap_delete(Relation relation, ItemPointer tid, CommandId cid, Snapshot crosscheck, bool wait, HeapUpdateFailureData *hufd)
Definition: heapam.c:3028
bool heap_hot_search(ItemPointer tid, Relation relation, Snapshot snapshot, bool *all_dead)
Definition: heapam.c:2156
void simple_heap_delete(Relation relation, ItemPointer tid)
Definition: heapam.c:3415
LockTupleMode
Definition: heapam.h:38
Relation relation_openrv_extended(const RangeVar *relation, LOCKMODE lockmode, bool missing_ok)
Definition: heapam.c:1233
BulkInsertState GetBulkInsertState(void)
Definition: heapam.c:2336
HeapTuple heap_getnext(HeapScanDesc scan, ScanDirection direction)
Definition: heapam.c:1808
Relation heap_openrv(const RangeVar *relation, LOCKMODE lockmode)
Definition: heapam.c:1318
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:6820
static char * buf
Definition: pg_test_fsync.c:67
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:4558
void heap_parallelscan_initialize(ParallelHeapScanDesc target, Relation relation, Snapshot snapshot)
Definition: heapam.c:1615
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:2413
HTSU_Result
Definition: snapshot.h:121
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:1425
void heap_update_snapshot(HeapScanDesc scan, Snapshot snapshot)
Definition: heapam.c:1774
bool heap_hot_search_buffer(ItemPointer tid, Relation relation, Buffer buffer, Snapshot snapshot, HeapTuple heapTuple, bool *all_dead, bool first_call)
Definition: heapam.c:2011
TransactionId xmax
Definition: heapam.h:71
struct ParallelHeapScanDescData * ParallelHeapScanDesc
Definition: heapam.h:101
Relation relation_openrv(const RangeVar *relation, LOCKMODE lockmode)
Definition: heapam.c:1198
HTSU_Result heap_update(Relation relation, ItemPointer otid, HeapTuple newtup, CommandId cid, Snapshot crosscheck, bool wait, HeapUpdateFailureData *hufd, LockTupleMode *lockmode)
Definition: heapam.c:3479
Size SyncScanShmemSize(void)
Definition: syncscan.c:126
TransactionId MultiXactId
Definition: c.h:401
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:350
Relation heap_openrv_extended(const RangeVar *relation, LOCKMODE lockmode, bool missing_ok)
Definition: heapam.c:1347
Oid simple_heap_insert(Relation relation, HeapTuple tup)
Definition: heapam.c:2956
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:7252
Relation heap_open(Oid relationId, LOCKMODE lockmode)
Definition: heapam.c:1290
void FreeBulkInsertState(BulkInsertState)
Definition: heapam.c:2350
void heap_get_latest_tid(Relation relation, Snapshot snapshot, ItemPointer tid)
Definition: heapam.c:2184
void relation_close(Relation relation, LOCKMODE lockmode)
Definition: heapam.c:1266
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:1546
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:6246
Relation try_relation_open(Oid relationId, LOCKMODE lockmode)
Definition: heapam.c:1153
void simple_heap_update(Relation relation, ItemPointer otid, HeapTuple tup)
Definition: heapam.c:4469
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:1415
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:2675
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:1433
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