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