1 /*-------------------------------------------------------------------------
2  *
3  * snapshot.h
4  *	  POSTGRES snapshot definition
5  *
6  * Portions Copyright (c) 1996-2018, 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 typedef struct SnapshotData *Snapshot;
24 
25 #define InvalidSnapshot		((Snapshot) NULL)
26 
27 /*
28  * We use SnapshotData structures to represent both "regular" (MVCC)
29  * snapshots and "special" snapshots that have non-MVCC semantics.
30  * The specific semantics of a snapshot are encoded by the "satisfies"
31  * function.
32  */
33 typedef bool (*SnapshotSatisfiesFunc) (HeapTuple htup,
34 									   Snapshot snapshot, Buffer buffer);
35 
36 /*
37  * Struct representing all kind of possible snapshots.
38  *
39  * There are several different kinds of snapshots:
40  * * Normal MVCC snapshots
41  * * MVCC snapshots taken during recovery (in Hot-Standby mode)
42  * * Historic MVCC snapshots used during logical decoding
43  * * snapshots passed to HeapTupleSatisfiesDirty()
44  * * snapshots passed to HeapTupleSatisfiesNonVacuumable()
45  * * snapshots used for SatisfiesAny, Toast, Self where no members are
46  *	 accessed.
47  *
48  * TODO: It's probably a good idea to split this struct using a NodeTag
49  * similar to how parser and executor nodes are handled, with one type for
50  * each different kind of snapshot to avoid overloading the meaning of
51  * individual fields.
52  */
53 typedef struct SnapshotData
54 {
55 	SnapshotSatisfiesFunc satisfies;	/* tuple test function */
56 
57 	/*
58 	 * The remaining fields are used only for MVCC snapshots, and are normally
59 	 * just zeroes in special snapshots.  (But xmin and xmax are used
60 	 * specially by HeapTupleSatisfiesDirty, and xmin is used specially by
61 	 * HeapTupleSatisfiesNonVacuumable.)
62 	 *
63 	 * An MVCC snapshot can never see the effects of XIDs >= xmax. It can see
64 	 * the effects of all older XIDs except those listed in the snapshot. xmin
65 	 * is stored as an optimization to avoid needing to search the XID arrays
66 	 * for most tuples.
67 	 */
68 	TransactionId xmin;			/* all XID < xmin are visible to me */
69 	TransactionId xmax;			/* all XID >= xmax are invisible to me */
70 
71 	/*
72 	 * For normal MVCC snapshot this contains the all xact IDs that are in
73 	 * progress, unless the snapshot was taken during recovery in which case
74 	 * it's empty. For historic MVCC snapshots, the meaning is inverted, i.e.
75 	 * it contains *committed* transactions between xmin and xmax.
76 	 *
77 	 * note: all ids in xip[] satisfy xmin <= xip[i] < xmax
78 	 */
79 	TransactionId *xip;
80 	uint32		xcnt;			/* # of xact ids in xip[] */
81 
82 	/*
83 	 * For non-historic MVCC snapshots, this contains subxact IDs that are in
84 	 * progress (and other transactions that are in progress if taken during
85 	 * recovery). For historic snapshot it contains *all* xids assigned to the
86 	 * replayed transaction, including the toplevel xid.
87 	 *
88 	 * note: all ids in subxip[] are >= xmin, but we don't bother filtering
89 	 * out any that are >= xmax
90 	 */
91 	TransactionId *subxip;
92 	int32		subxcnt;		/* # of xact ids in subxip[] */
93 	bool		suboverflowed;	/* has the subxip array overflowed? */
94 
95 	bool		takenDuringRecovery;	/* recovery-shaped snapshot? */
96 	bool		copied;			/* false if it's a static snapshot */
97 
98 	CommandId	curcid;			/* in my xact, CID < curcid are visible */
99 
100 	/*
101 	 * An extra return value for HeapTupleSatisfiesDirty, not used in MVCC
102 	 * snapshots.
103 	 */
104 	uint32		speculativeToken;
105 
106 	/*
107 	 * Book-keeping information, used by the snapshot manager
108 	 */
109 	uint32		active_count;	/* refcount on ActiveSnapshot stack */
110 	uint32		regd_count;		/* refcount on RegisteredSnapshots */
111 	pairingheap_node ph_node;	/* link in the RegisteredSnapshots heap */
112 
113 	TimestampTz whenTaken;		/* timestamp when snapshot was taken */
114 	XLogRecPtr	lsn;			/* position in the WAL stream when taken */
115 } SnapshotData;
116 
117 /*
118  * Result codes for HeapTupleSatisfiesUpdate.  This should really be in
119  * tqual.h, but we want to avoid including that file elsewhere.
120  */
121 typedef enum
122 {
123 	HeapTupleMayBeUpdated,
124 	HeapTupleInvisible,
125 	HeapTupleSelfUpdated,
126 	HeapTupleUpdated,
127 	HeapTupleBeingUpdated,
128 	HeapTupleWouldBlock			/* can be returned by heap_tuple_lock */
129 } HTSU_Result;
130 
131 #endif							/* SNAPSHOT_H */
132