codekingpro/portable-devtools

1/*-------------------------------------------------------------------------2 *3 * snapshot.h4 *	  POSTGRES snapshot definition5 *6 * Portions Copyright (c) 1996-2023, PostgreSQL Global Development Group7 * Portions Copyright (c) 1994, Regents of the University of California8 *9 * src/include/utils/snapshot.h10 *11 *-------------------------------------------------------------------------12 */13#ifndef SNAPSHOT_H14#define SNAPSHOT_H15 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 represent25 * both "regular" (MVCC) snapshots and "special" snapshots that have non-MVCC26 * 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 its29 * 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 is32 * that that allows to use the same snapshot for different table AMs without33 * having one callback per AM.34 */35typedef enum SnapshotType36{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 snapshot42	 * - previous commands of this transaction43	 *44	 * Does _not_ include:45	 * - transactions shown as in-progress by the snapshot46	 * - transactions started after the snapshot was taken47	 * - changes made by the current command48	 * -------------------------------------------------------------------------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 transaction58	 * - changes made by the current command59	 *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 open78	 * 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 transaction83	 * - changes made by the current command84	 *85	 * This is essentially like SNAPSHOT_SELF as far as effects of the current86	 * transaction and committed/aborted xacts are concerned.  However, it87	 * 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 to90	 * determine tuple visibility, the passed-in snapshot struct is used as an91	 * output argument to return the xids of concurrent xacts that affected92	 * the tuple.  snapshot->xmin is set to the tuple's xmin if that is93	 * another transaction that's still in progress; or to94	 * InvalidTransactionId if the tuple's xmin is committed good, committed95	 * dead, or my own xact.  Similarly for snapshot->xmax and the tuple's96	 * xmax.  If the tuple was inserted speculatively, meaning that the97	 * inserter might still back down on the insertion without aborting the98	 * whole transaction, the associated token is also returned in99	 * 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, but106	 * supports being called in timetravel context (for decoding catalog107	 * 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 xmin116	 * horizon to use.117	 */118	SNAPSHOT_NON_VACUUMABLE119} SnapshotType;120 121typedef 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 snapshots130 * * MVCC snapshots taken during recovery (in Hot-Standby mode)131 * * Historic MVCC snapshots used during logical decoding132 * * snapshots passed to HeapTupleSatisfiesDirty()133 * * snapshots passed to HeapTupleSatisfiesNonVacuumable()134 * * snapshots used for SatisfiesAny, Toast, Self where no members are135 *	 accessed.136 *137 * TODO: It's probably a good idea to split this struct using a NodeTag138 * similar to how parser and executor nodes are handled, with one type for139 * each different kind of snapshot to avoid overloading the meaning of140 * individual fields.141 */142typedef struct SnapshotData143{144	SnapshotType snapshot_type; /* type of snapshot */145 146	/*147	 * The remaining fields are used only for MVCC snapshots, and are normally148	 * just zeroes in special snapshots.  (But xmin and xmax are used149	 * specially by HeapTupleSatisfiesDirty, and xmin is used specially by150	 * HeapTupleSatisfiesNonVacuumable.)151	 *152	 * An MVCC snapshot can never see the effects of XIDs >= xmax. It can see153	 * the effects of all older XIDs except those listed in the snapshot. xmin154	 * is stored as an optimization to avoid needing to search the XID arrays155	 * 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 in162	 * progress, unless the snapshot was taken during recovery in which case163	 * 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] < xmax167	 */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 in173	 * progress (and other transactions that are in progress if taken during174	 * recovery). For historic snapshot it contains *all* xids assigned to the175	 * replayed transaction, including the toplevel xid.176	 *177	 * note: all ids in subxip[] are >= xmin, but we don't bother filtering178	 * out any that are >= xmax179	 */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 MVCC191	 * snapshots.192	 */193	uint32		speculativeToken;194 195	/*196	 * For SNAPSHOT_NON_VACUUMABLE (and hopefully more in the future) this is197	 * used to determine whether row could be vacuumed.198	 */199	struct GlobalVisState *vistest;200 201	/*202	 * Book-keeping information, used by the snapshot manager203	 */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() built213	 * this snapshot. Allows to avoid re-computing static snapshots when no214	 * transactions completed since the last GetSnapshotData().215	 */216	uint64		snapXactCompletionCount;217} SnapshotData;218 219#endif							/* SNAPSHOT_H */220