1/*-------------------------------------------------------------------------
4 * postgres transaction access method support code
7 * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
8 * Portions Copyright (c) 1994, Regents of the University of California
10 * src/include/access/transam.h
12 *-------------------------------------------------------------------------
21 * Special transaction ID values
23 * BootstrapTransactionId is the XID for "bootstrap" operations, and
24 * FrozenTransactionId is used for very old tuples. Both should
25 * always be considered valid.
27 * FirstNormalTransactionId is the first "normal" transaction id.
28 * Note: if you need to change it, you must change pg_class.h as well.
31 #define InvalidTransactionId ((TransactionId) 0)
32 #define BootstrapTransactionId ((TransactionId) 1)
33 #define FrozenTransactionId ((TransactionId) 2)
34 #define FirstNormalTransactionId ((TransactionId) 3)
35 #define MaxTransactionId ((TransactionId) 0xFFFFFFFF)
38 * transaction ID manipulation macros
41 #define TransactionIdIsValid(xid) ((xid) != InvalidTransactionId)
42 #define TransactionIdIsNormal(xid) ((xid) >= FirstNormalTransactionId)
43 #define TransactionIdEquals(id1, id2) ((id1) == (id2))
44 #define TransactionIdStore(xid, dest) (*(dest) = (xid))
45 #define StoreInvalidTransactionId(dest) (*(dest) = InvalidTransactionId)
47 #define EpochFromFullTransactionId(x) ((uint32) ((x).value >> 32))
48 #define XidFromFullTransactionId(x) ((uint32) (x).value)
49 #define U64FromFullTransactionId(x) ((x).value)
50 #define FullTransactionIdEquals(a, b) ((a).value == (b).value)
51 #define FullTransactionIdPrecedes(a, b) ((a).value < (b).value)
52 #define FullTransactionIdPrecedesOrEquals(a, b) ((a).value <= (b).value)
53 #define FullTransactionIdFollows(a, b) ((a).value > (b).value)
54 #define FullTransactionIdFollowsOrEquals(a, b) ((a).value >= (b).value)
55 #define FullTransactionIdIsValid(x) TransactionIdIsValid(XidFromFullTransactionId(x))
56 #define InvalidFullTransactionId FullTransactionIdFromEpochAndXid(0, InvalidTransactionId)
57 #define FirstNormalFullTransactionId FullTransactionIdFromEpochAndXid(0, FirstNormalTransactionId)
58 #define FullTransactionIdIsNormal(x) FullTransactionIdFollowsOrEquals(x, FirstNormalFullTransactionId)
61 * A 64 bit value that contains an epoch and a TransactionId. This is
62 * wrapped in a struct to prevent implicit conversion to/from TransactionId.
63 * Not all values represent valid normal XIDs.
90/* advance a transaction ID variable, handling wraparound correctly */
91 #define TransactionIdAdvance(dest) \
94 if ((dest) < FirstNormalTransactionId) \
95 (dest) = FirstNormalTransactionId; \
99 * Retreat a FullTransactionId variable, stepping over xids that would appear
100 * to be special only when viewed as 32bit XIDs.
108 * In contrast to 32bit XIDs don't step over the "actual" special xids.
109 * For 64bit xids these can't be reached as part of a wraparound as they
110 * can in the 32bit case.
116 * But we do need to step over XIDs that'd appear special only for 32bit
124 * Advance a FullTransactionId variable, stepping over xids that would appear
125 * to be special only when viewed as 32bit XIDs.
132 /* see FullTransactionIdAdvance() */
140/* back up a transaction ID variable, handling wraparound correctly */
141 #define TransactionIdRetreat(dest) \
144 } while ((dest) < FirstNormalTransactionId)
146/* compare two XIDs already known to be normal; this is a macro for speed */
147 #define NormalTransactionIdPrecedes(id1, id2) \
148 (AssertMacro(TransactionIdIsNormal(id1) && TransactionIdIsNormal(id2)), \
149 (int32) ((id1) - (id2)) < 0)
151/* compare two XIDs already known to be normal; this is a macro for speed */
152 #define NormalTransactionIdFollows(id1, id2) \
153 (AssertMacro(TransactionIdIsNormal(id1) && TransactionIdIsNormal(id2)), \
154 (int32) ((id1) - (id2)) > 0)
157 * Object ID (OID) zero is InvalidOid.
159 * OIDs 1-9999 are reserved for manual assignment (see .dat files in
160 * src/include/catalog/). Of these, 8000-9999 are reserved for
161 * development purposes (such as in-progress patches and forks);
162 * they should not appear in released versions.
164 * OIDs 10000-11999 are reserved for assignment by genbki.pl, for use
165 * when the .dat files in src/include/catalog/ do not specify an OID
166 * for a catalog entry that requires one. Note that genbki.pl assigns
167 * these OIDs independently in each catalog, so they're not guaranteed
168 * to be globally unique. Furthermore, the bootstrap backend and
169 * initdb's post-bootstrap processing can also assign OIDs in this range.
170 * The normal OID-generation logic takes care of any OID conflicts that
171 * might arise from that.
173 * OIDs 12000-16383 are reserved for unpinned objects created by initdb's
174 * post-bootstrap processing. initdb forces the OID generator up to
175 * 12000 as soon as it's made the pinned objects it's responsible for.
177 * OIDs beginning at 16384 are assigned from the OID generator
178 * during normal multiuser operation. (We force the generator up to
179 * 16384 as soon as we are in normal operation.)
181 * The choices of 8000, 10000 and 12000 are completely arbitrary, and can be
182 * moved if we run low on OIDs in any category. Changing the macros below,
183 * and updating relevant documentation (see bki.sgml and RELEASE_CHANGES),
184 * should be sufficient to do this. Moving the 16384 boundary between
185 * initdb-assigned OIDs and user-defined objects would be substantially
186 * more painful, however, since some user-defined OIDs will appear in
187 * on-disk data; such a change would probably break pg_upgrade.
189 * NOTE: if the OID generator wraps around, we skip over OIDs 0-16383
190 * and resume with 16384. This minimizes the odds of OID conflict, by not
191 * reassigning OIDs that might have been assigned during initdb. Critically,
192 * it also ensures that no user-created object will be considered pinned.
195 #define FirstGenbkiObjectId 10000
196 #define FirstUnpinnedObjectId 12000
197 #define FirstNormalObjectId 16384
200 * TransamVariables is a data structure in shared memory that is used to track
201 * OID and XID assignment state. For largely historical reasons, there is
202 * just one struct with different fields that are protected by different
205 * Note: xidWrapLimit and oldestXidDB are not "active" values, but are
206 * used just to generate useful messages when xidWarnLimit or xidStopLimit
212 * These fields are protected by OidGenLock.
218 * These fields are protected by XidGenLock.
230 * These fields are protected by CommitTsLock
236 * These fields are protected by ProcArrayLock.
239 * committed or aborted */
242 * Number of top-level transactions with xids (i.e. which may have
243 * modified the database) that completed in some form since the start of
244 * the server. This currently is solely used to check whether
245 * GetSnapshotData() needs to recompute the contents of the snapshot, or
246 * not. There are likely other users of this. Always above 1.
251 * These fields are protected by XactTruncationLock
259 * extern declarations
263/* in transam/xact.c */
266/* in transam/varsup.c */
270 * prototypes for functions in transam/transam.c
285/* in transam/varsup.c */
298#ifdef USE_ASSERT_CHECKING
301 #define AssertTransactionIdInAllowableRange(xid) ((void)true)
305 * Some frontend programs include this header. For compilers that emit static
306 * inline functions even when they're unused, that leads to unsatisfied
307 * external references; hence hide them with #ifndef FRONTEND.
312 * For callers that just need the XID part of the next transaction ID.
320/* return transaction ID backed up by amount, handling wraparound correctly */
332/* return the older of the two IDs */
347/* return the older of the two IDs, assuming they're both normal */
358/* return the newer of the two IDs */
374 * Compute FullTransactionId for the given TransactionId, assuming xid was
375 * between [oldestXid, nextXid] at the time when TransamVariables->nextXid was
376 * nextFullXid. When adding calls, evaluate what prevents xid from preceding
377 * oldestXid if SetTransactionIdLimit() runs between the collection of xid and
378 * the collection of nextFullXid.
386 /* Special transaction ID. */
394 * The 64 bit result must be <= nextFullXid, since nextFullXid hadn't been
395 * issued yet when xid was in the past. The xid must therefore be from
396 * the epoch of nextFullXid or the epoch before. We know this because we
397 * must remove (by freezing) an XID before assigning the XID half an epoch
400 * The unlikely() branch hint is dubious. It's perfect for the first 2^32
401 * XIDs of a cluster's life. Right at 2^32 XIDs, misprediction shoots to
402 * 100%, then improves until perfection returns 2^31 XIDs later. Since
403 * current callers pass relatively-recent XIDs, expect >90% prediction
404 * accuracy overall. This favors average latency over tail latency.
418#endif /* TRANSAM_H */
Assert(PointerIsAligned(start, uint64))
TransactionId xidStopLimit
TransactionId oldestCommitTsXid
TransactionId newestCommitTsXid
TransactionId xidWarnLimit
TransactionId xidWrapLimit
FullTransactionId latestCompletedXid
FullTransactionId nextXid
TransactionId xidVacLimit
uint64 xactCompletionCount
TransactionId oldestClogXid
void TransactionIdAsyncCommitTree(TransactionId xid, int nxids, TransactionId *xids, XLogRecPtr lsn)
PGDLLIMPORT TransamVariablesData * TransamVariables
FullTransactionId ReadNextFullTransactionId(void)
void AdvanceNextFullTransactionIdPastXid(TransactionId xid)
static TransactionId ReadNextTransactionId(void)
static TransactionId TransactionIdRetreatedBy(TransactionId xid, uint32 amount)
static FullTransactionId FullTransactionIdNewer(FullTransactionId a, FullTransactionId b)
TransactionId TransactionIdLatest(TransactionId mainxid, int nxids, const TransactionId *xids)
static FullTransactionId FullTransactionIdFromAllowableAt(FullTransactionId nextFullXid, TransactionId xid)
static void FullTransactionIdRetreat(FullTransactionId *dest)
#define EpochFromFullTransactionId(x)
bool TransactionStartedDuringRecovery(void)
static FullTransactionId FullTransactionIdFromU64(uint64 value)
void SetTransactionIdLimit(TransactionId oldest_datfrozenxid, Oid oldest_datoid)
#define AssertTransactionIdInAllowableRange(xid)
bool TransactionIdDidCommit(TransactionId transactionId)
void TransactionIdCommitTree(TransactionId xid, int nxids, TransactionId *xids)
static TransactionId NormalTransactionIdOlder(TransactionId a, TransactionId b)
Size VarsupShmemSize(void)
FullTransactionId GetNewTransactionId(bool isSubXact)
#define NormalTransactionIdPrecedes(id1, id2)
void StopGeneratingPinnedObjectIds(void)
void TransactionIdAbortTree(TransactionId xid, int nxids, TransactionId *xids)
bool TransactionIdPrecedes(TransactionId id1, TransactionId id2)
bool ForceTransactionIdLimitUpdate(void)
#define FullTransactionIdFollows(a, b)
#define XidFromFullTransactionId(x)
bool TransactionIdPrecedesOrEquals(TransactionId id1, TransactionId id2)
bool TransactionIdDidAbort(TransactionId transactionId)
bool TransactionIdFollows(TransactionId id1, TransactionId id2)
XLogRecPtr TransactionIdGetCommitLSN(TransactionId xid)
void AdvanceOldestClogXid(TransactionId oldest_datfrozenxid)
#define FirstNormalTransactionId
static void FullTransactionIdAdvance(FullTransactionId *dest)
struct TransamVariablesData TransamVariablesData
#define TransactionIdIsValid(xid)
static FullTransactionId FullTransactionIdFromEpochAndXid(uint32 epoch, TransactionId xid)
struct FullTransactionId FullTransactionId
#define TransactionIdIsNormal(xid)
#define FirstNormalFullTransactionId
#define FullTransactionIdPrecedes(a, b)
#define FullTransactionIdIsValid(x)
static TransactionId TransactionIdOlder(TransactionId a, TransactionId b)
void VarsupShmemInit(void)
bool TransactionIdFollowsOrEquals(TransactionId id1, TransactionId id2)
static const unsigned __int64 epoch