PostgreSQL Source Code
git master
snapshot.h
Go to the documentation of this file.
1
/*-------------------------------------------------------------------------
2
*
3
* snapshot.h
4
* POSTGRES snapshot definition
5
*
6
* Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
7
* Portions Copyright (c) 1994, Regents of the University of California
8
*
9
* src/include/utils/snapshot.h
10
*
11
*-------------------------------------------------------------------------
12
*/
13
#ifndef SNAPSHOT_H
14
#define SNAPSHOT_H
15
16
#include "
access/htup.h
"
17
#include "
access/xlogdefs.h
"
18
#include "
datatype/timestamp.h
"
19
#include "
lib/pairingheap.h
"
20
#include "
storage/buf.h
"
21
22
23
/*
24
* The different snapshot types. We use SnapshotData structures to represent
25
* both "regular" (MVCC) snapshots and "special" snapshots that have non-MVCC
26
* semantics. The specific semantics of a snapshot are encoded by its type.
27
*
28
* The behaviour of each type of snapshot should be documented alongside its
29
* enum value, best in terms that are not specific to an individual table AM.
30
*
31
* The reason the snapshot type rather than a callback as it used to be is
32
* that that allows to use the same snapshot for different table AMs without
33
* having one callback per AM.
34
*/
35
typedef
enum
SnapshotType
36
{
37
/*-------------------------------------------------------------------------
38
* A tuple is visible iff the tuple is valid for the given MVCC snapshot.
39
*
40
* Here, we consider the effects of:
41
* - all transactions committed as of the time of the given snapshot
42
* - previous commands of this transaction
43
*
44
* Does _not_ include:
45
* - transactions shown as in-progress by the snapshot
46
* - transactions started after the snapshot was taken
47
* - changes made by the current command
48
* -------------------------------------------------------------------------
49
*/
50
SNAPSHOT_MVCC
= 0,
51
52
/*-------------------------------------------------------------------------
53
* A tuple is visible iff the tuple is valid "for itself".
54
*
55
* Here, we consider the effects of:
56
* - all committed transactions (as of the current instant)
57
* - previous commands of this transaction
58
* - changes made by the current command
59
*
60
* Does _not_ include:
61
* - in-progress transactions (as of the current instant)
62
* -------------------------------------------------------------------------
63
*/
64
SNAPSHOT_SELF
,
65
66
/*
67
* Any tuple is visible.
68
*/
69
SNAPSHOT_ANY
,
70
71
/*
72
* A tuple is visible iff the tuple is valid as a TOAST row.
73
*/
74
SNAPSHOT_TOAST
,
75
76
/*-------------------------------------------------------------------------
77
* A tuple is visible iff the tuple is valid including effects of open
78
* transactions.
79
*
80
* Here, we consider the effects of:
81
* - all committed and in-progress transactions (as of the current instant)
82
* - previous commands of this transaction
83
* - changes made by the current command
84
*
85
* This is essentially like SNAPSHOT_SELF as far as effects of the current
86
* transaction and committed/aborted xacts are concerned. However, it
87
* also includes the effects of other xacts still in progress.
88
*
89
* A special hack is that when a snapshot of this type is used to
90
* determine tuple visibility, the passed-in snapshot struct is used as an
91
* output argument to return the xids of concurrent xacts that affected
92
* the tuple. snapshot->xmin is set to the tuple's xmin if that is
93
* another transaction that's still in progress; or to
94
* InvalidTransactionId if the tuple's xmin is committed good, committed
95
* dead, or my own xact. Similarly for snapshot->xmax and the tuple's
96
* xmax. If the tuple was inserted speculatively, meaning that the
97
* inserter might still back down on the insertion without aborting the
98
* whole transaction, the associated token is also returned in
99
* snapshot->speculativeToken. See also InitDirtySnapshot().
100
* -------------------------------------------------------------------------
101
*/
102
SNAPSHOT_DIRTY
,
103
104
/*
105
* A tuple is visible iff it follows the rules of SNAPSHOT_MVCC, but
106
* supports being called in timetravel context (for decoding catalog
107
* contents in the context of logical decoding).
108
*/
109
SNAPSHOT_HISTORIC_MVCC
,
110
111
/*
112
* A tuple is visible iff the tuple might be visible to some transaction;
113
* false if it's surely dead to everyone, i.e., vacuumable.
114
*
115
* For visibility checks snapshot->min must have been set up with the xmin
116
* horizon to use.
117
*/
118
SNAPSHOT_NON_VACUUMABLE
,
119
}
SnapshotType
;
120
121
typedef
struct
SnapshotData
*
Snapshot
;
122
123
#define InvalidSnapshot ((Snapshot) NULL)
124
125
/*
126
* Struct representing all kind of possible snapshots.
127
*
128
* There are several different kinds of snapshots:
129
* * Normal MVCC snapshots
130
* * MVCC snapshots taken during recovery (in Hot-Standby mode)
131
* * Historic MVCC snapshots used during logical decoding
132
* * snapshots passed to HeapTupleSatisfiesDirty()
133
* * snapshots passed to HeapTupleSatisfiesNonVacuumable()
134
* * snapshots used for SatisfiesAny, Toast, Self where no members are
135
* accessed.
136
*
137
* TODO: It's probably a good idea to split this struct using a NodeTag
138
* similar to how parser and executor nodes are handled, with one type for
139
* each different kind of snapshot to avoid overloading the meaning of
140
* individual fields.
141
*/
142
typedef
struct
SnapshotData
143
{
144
SnapshotType
snapshot_type
;
/* type of snapshot */
145
146
/*
147
* The remaining fields are used only for MVCC snapshots, and are normally
148
* just zeroes in special snapshots. (But xmin and xmax are used
149
* specially by HeapTupleSatisfiesDirty, and xmin is used specially by
150
* HeapTupleSatisfiesNonVacuumable.)
151
*
152
* An MVCC snapshot can never see the effects of XIDs >= xmax. It can see
153
* the effects of all older XIDs except those listed in the snapshot. xmin
154
* is stored as an optimization to avoid needing to search the XID arrays
155
* for most tuples.
156
*/
157
TransactionId
xmin
;
/* all XID < xmin are visible to me */
158
TransactionId
xmax
;
/* all XID >= xmax are invisible to me */
159
160
/*
161
* For normal MVCC snapshot this contains the all xact IDs that are in
162
* progress, unless the snapshot was taken during recovery in which case
163
* it's empty. For historic MVCC snapshots, the meaning is inverted, i.e.
164
* it contains *committed* transactions between xmin and xmax.
165
*
166
* note: all ids in xip[] satisfy xmin <= xip[i] < xmax
167
*/
168
TransactionId
*
xip
;
169
uint32
xcnt
;
/* # of xact ids in xip[] */
170
171
/*
172
* For non-historic MVCC snapshots, this contains subxact IDs that are in
173
* progress (and other transactions that are in progress if taken during
174
* recovery). For historic snapshot it contains *all* xids assigned to the
175
* replayed transaction, including the toplevel xid.
176
*
177
* note: all ids in subxip[] are >= xmin, but we don't bother filtering
178
* out any that are >= xmax
179
*/
180
TransactionId
*
subxip
;
181
int32
subxcnt
;
/* # of xact ids in subxip[] */
182
bool
suboverflowed
;
/* has the subxip array overflowed? */
183
184
bool
takenDuringRecovery
;
/* recovery-shaped snapshot? */
185
bool
copied
;
/* false if it's a static snapshot */
186
187
CommandId
curcid
;
/* in my xact, CID < curcid are visible */
188
189
/*
190
* An extra return value for HeapTupleSatisfiesDirty, not used in MVCC
191
* snapshots.
192
*/
193
uint32
speculativeToken
;
194
195
/*
196
* For SNAPSHOT_NON_VACUUMABLE (and hopefully more in the future) this is
197
* used to determine whether row could be vacuumed.
198
*/
199
struct
GlobalVisState
*
vistest
;
200
201
/*
202
* Book-keeping information, used by the snapshot manager
203
*/
204
uint32
active_count
;
/* refcount on ActiveSnapshot stack */
205
uint32
regd_count
;
/* refcount on RegisteredSnapshots */
206
pairingheap_node
ph_node
;
/* link in the RegisteredSnapshots heap */
207
208
TimestampTz
whenTaken
;
/* timestamp when snapshot was taken */
209
XLogRecPtr
lsn
;
/* position in the WAL stream when taken */
210
211
/*
212
* The transaction completion count at the time GetSnapshotData() built
213
* this snapshot. Allows to avoid re-computing static snapshots when no
214
* transactions completed since the last GetSnapshotData().
215
*/
216
uint64
snapXactCompletionCount
;
217
}
SnapshotData
;
218
219
#endif
/* SNAPSHOT_H */
buf.h
uint32
unsigned int uint32
Definition:
c.h:506
int32
signed int int32
Definition:
c.h:496
CommandId
uint32 CommandId
Definition:
c.h:657
TransactionId
uint32 TransactionId
Definition:
c.h:643
timestamp.h
TimestampTz
int64 TimestampTz
Definition:
timestamp.h:39
htup.h
pairingheap.h
Snapshot
struct SnapshotData * Snapshot
Definition:
snapshot.h:121
SnapshotData
struct SnapshotData SnapshotData
SnapshotType
SnapshotType
Definition:
snapshot.h:36
SNAPSHOT_TOAST
@ SNAPSHOT_TOAST
Definition:
snapshot.h:74
SNAPSHOT_SELF
@ SNAPSHOT_SELF
Definition:
snapshot.h:64
SNAPSHOT_NON_VACUUMABLE
@ SNAPSHOT_NON_VACUUMABLE
Definition:
snapshot.h:118
SNAPSHOT_MVCC
@ SNAPSHOT_MVCC
Definition:
snapshot.h:50
SNAPSHOT_ANY
@ SNAPSHOT_ANY
Definition:
snapshot.h:69
SNAPSHOT_HISTORIC_MVCC
@ SNAPSHOT_HISTORIC_MVCC
Definition:
snapshot.h:109
SNAPSHOT_DIRTY
@ SNAPSHOT_DIRTY
Definition:
snapshot.h:102
GlobalVisState
Definition:
procarray.c:168
SnapshotData
Definition:
snapshot.h:143
SnapshotData::xmin
TransactionId xmin
Definition:
snapshot.h:157
SnapshotData::subxcnt
int32 subxcnt
Definition:
snapshot.h:181
SnapshotData::copied
bool copied
Definition:
snapshot.h:185
SnapshotData::regd_count
uint32 regd_count
Definition:
snapshot.h:205
SnapshotData::active_count
uint32 active_count
Definition:
snapshot.h:204
SnapshotData::curcid
CommandId curcid
Definition:
snapshot.h:187
SnapshotData::vistest
struct GlobalVisState * vistest
Definition:
snapshot.h:199
SnapshotData::ph_node
pairingheap_node ph_node
Definition:
snapshot.h:206
SnapshotData::whenTaken
TimestampTz whenTaken
Definition:
snapshot.h:208
SnapshotData::xcnt
uint32 xcnt
Definition:
snapshot.h:169
SnapshotData::subxip
TransactionId * subxip
Definition:
snapshot.h:180
SnapshotData::snapXactCompletionCount
uint64 snapXactCompletionCount
Definition:
snapshot.h:216
SnapshotData::xmax
TransactionId xmax
Definition:
snapshot.h:158
SnapshotData::lsn
XLogRecPtr lsn
Definition:
snapshot.h:209
SnapshotData::speculativeToken
uint32 speculativeToken
Definition:
snapshot.h:193
SnapshotData::snapshot_type
SnapshotType snapshot_type
Definition:
snapshot.h:144
SnapshotData::xip
TransactionId * xip
Definition:
snapshot.h:168
SnapshotData::suboverflowed
bool suboverflowed
Definition:
snapshot.h:182
SnapshotData::takenDuringRecovery
bool takenDuringRecovery
Definition:
snapshot.h:184
pairingheap_node
Definition:
pairingheap.h:31
xlogdefs.h
XLogRecPtr
uint64 XLogRecPtr
Definition:
xlogdefs.h:21
src
include
utils
snapshot.h
Generated on Tue Nov 5 2024 06:13:26 for PostgreSQL Source Code by
1.9.1