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  */
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  */
65 
66  /*
67  * Any tuple is visible.
68  */
70 
71  /*
72  * A tuple is visible iff the tuple is valid as a TOAST row.
73  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
218 
219 #endif /* SNAPSHOT_H */
unsigned int uint32
Definition: c.h:506
signed int int32
Definition: c.h:496
uint32 CommandId
Definition: c.h:657
uint32 TransactionId
Definition: c.h:643
int64 TimestampTz
Definition: timestamp.h:39
struct SnapshotData * Snapshot
Definition: snapshot.h:121
struct SnapshotData SnapshotData
SnapshotType
Definition: snapshot.h:36
@ SNAPSHOT_TOAST
Definition: snapshot.h:74
@ SNAPSHOT_SELF
Definition: snapshot.h:64
@ SNAPSHOT_NON_VACUUMABLE
Definition: snapshot.h:118
@ SNAPSHOT_MVCC
Definition: snapshot.h:50
@ SNAPSHOT_ANY
Definition: snapshot.h:69
@ SNAPSHOT_HISTORIC_MVCC
Definition: snapshot.h:109
@ SNAPSHOT_DIRTY
Definition: snapshot.h:102
TransactionId xmin
Definition: snapshot.h:157
int32 subxcnt
Definition: snapshot.h:181
bool copied
Definition: snapshot.h:185
uint32 regd_count
Definition: snapshot.h:205
uint32 active_count
Definition: snapshot.h:204
CommandId curcid
Definition: snapshot.h:187
struct GlobalVisState * vistest
Definition: snapshot.h:199
pairingheap_node ph_node
Definition: snapshot.h:206
TimestampTz whenTaken
Definition: snapshot.h:208
uint32 xcnt
Definition: snapshot.h:169
TransactionId * subxip
Definition: snapshot.h:180
uint64 snapXactCompletionCount
Definition: snapshot.h:216
TransactionId xmax
Definition: snapshot.h:158
XLogRecPtr lsn
Definition: snapshot.h:209
uint32 speculativeToken
Definition: snapshot.h:193
SnapshotType snapshot_type
Definition: snapshot.h:144
TransactionId * xip
Definition: snapshot.h:168
bool suboverflowed
Definition: snapshot.h:182
bool takenDuringRecovery
Definition: snapshot.h:184
uint64 XLogRecPtr
Definition: xlogdefs.h:21