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