PostgreSQL Source Code git master
All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
transam.h
Go to the documentation of this file.
1/*-------------------------------------------------------------------------
2 *
3 * transam.h
4 * postgres transaction access method support code
5 *
6 *
7 * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
8 * Portions Copyright (c) 1994, Regents of the University of California
9 *
10 * src/include/access/transam.h
11 *
12 *-------------------------------------------------------------------------
13 */
14#ifndef TRANSAM_H
15#define TRANSAM_H
16
17#include "access/xlogdefs.h"
18
19
20/* ----------------
21 * Special transaction ID values
22 *
23 * BootstrapTransactionId is the XID for "bootstrap" operations, and
24 * FrozenTransactionId is used for very old tuples. Both should
25 * always be considered valid.
26 *
27 * FirstNormalTransactionId is the first "normal" transaction id.
28 * Note: if you need to change it, you must change pg_class.h as well.
29 * ----------------
30 */
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)
36
37/* ----------------
38 * transaction ID manipulation macros
39 * ----------------
40 */
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)
46
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)
59
60/*
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.
64 */
65typedef struct FullTransactionId
66{
69
70static inline FullTransactionId
72{
73 FullTransactionId result;
74
75 result.value = ((uint64) epoch) << 32 | xid;
76
77 return result;
78}
79
80static inline FullTransactionId
82{
83 FullTransactionId result;
84
85 result.value = value;
86
87 return result;
88}
89
90/* advance a transaction ID variable, handling wraparound correctly */
91#define TransactionIdAdvance(dest) \
92 do { \
93 (dest)++; \
94 if ((dest) < FirstNormalTransactionId) \
95 (dest) = FirstNormalTransactionId; \
96 } while(0)
97
98/*
99 * Retreat a FullTransactionId variable, stepping over xids that would appear
100 * to be special only when viewed as 32bit XIDs.
101 */
102static inline void
104{
105 dest->value--;
106
107 /*
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.
111 */
113 return;
114
115 /*
116 * But we do need to step over XIDs that'd appear special only for 32bit
117 * XIDs.
118 */
120 dest->value--;
121}
122
123/*
124 * Advance a FullTransactionId variable, stepping over xids that would appear
125 * to be special only when viewed as 32bit XIDs.
126 */
127static inline void
129{
130 dest->value++;
131
132 /* see FullTransactionIdAdvance() */
134 return;
135
137 dest->value++;
138}
139
140/* back up a transaction ID variable, handling wraparound correctly */
141#define TransactionIdRetreat(dest) \
142 do { \
143 (dest)--; \
144 } while ((dest) < FirstNormalTransactionId)
145
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)
150
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)
155
156/* ----------
157 * Object ID (OID) zero is InvalidOid.
158 *
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.
163 *
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.
172 *
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.
176 *
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.)
180 *
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.
188 *
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.
193 * ----------
194 */
195#define FirstGenbkiObjectId 10000
196#define FirstUnpinnedObjectId 12000
197#define FirstNormalObjectId 16384
198
199/*
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
203 * LWLocks.
204 *
205 * Note: xidWrapLimit and oldestXidDB are not "active" values, but are
206 * used just to generate useful messages when xidWarnLimit or xidStopLimit
207 * are exceeded.
208 */
210{
211 /*
212 * These fields are protected by OidGenLock.
213 */
214 Oid nextOid; /* next OID to assign */
215 uint32 oidCount; /* OIDs available before must do XLOG work */
216
217 /*
218 * These fields are protected by XidGenLock.
219 */
220 FullTransactionId nextXid; /* next XID to assign */
221
222 TransactionId oldestXid; /* cluster-wide minimum datfrozenxid */
223 TransactionId xidVacLimit; /* start forcing autovacuums here */
224 TransactionId xidWarnLimit; /* start complaining here */
225 TransactionId xidStopLimit; /* refuse to advance nextXid beyond here */
226 TransactionId xidWrapLimit; /* where the world ends */
227 Oid oldestXidDB; /* database with minimum datfrozenxid */
228
229 /*
230 * These fields are protected by CommitTsLock
231 */
234
235 /*
236 * These fields are protected by ProcArrayLock.
237 */
238 FullTransactionId latestCompletedXid; /* newest full XID that has
239 * committed or aborted */
240
241 /*
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.
247 */
249
250 /*
251 * These fields are protected by XactTruncationLock
252 */
253 TransactionId oldestClogXid; /* oldest it's safe to look up in clog */
254
256
257
258/* ----------------
259 * extern declarations
260 * ----------------
261 */
262
263/* in transam/xact.c */
264extern bool TransactionStartedDuringRecovery(void);
265
266/* in transam/varsup.c */
268
269/*
270 * prototypes for functions in transam/transam.c
271 */
272extern bool TransactionIdDidCommit(TransactionId transactionId);
273extern bool TransactionIdDidAbort(TransactionId transactionId);
274extern void TransactionIdCommitTree(TransactionId xid, int nxids, TransactionId *xids);
275extern void TransactionIdAsyncCommitTree(TransactionId xid, int nxids, TransactionId *xids, XLogRecPtr lsn);
276extern void TransactionIdAbortTree(TransactionId xid, int nxids, TransactionId *xids);
282 int nxids, const TransactionId *xids);
284
285/* in transam/varsup.c */
286extern Size VarsupShmemSize(void);
287extern void VarsupShmemInit(void);
288extern FullTransactionId GetNewTransactionId(bool isSubXact);
291extern void SetTransactionIdLimit(TransactionId oldest_datfrozenxid,
292 Oid oldest_datoid);
293extern void AdvanceOldestClogXid(TransactionId oldest_datfrozenxid);
294extern bool ForceTransactionIdLimitUpdate(void);
295extern Oid GetNewObjectId(void);
296extern void StopGeneratingPinnedObjectIds(void);
297
298#ifdef USE_ASSERT_CHECKING
300#else
301#define AssertTransactionIdInAllowableRange(xid) ((void)true)
302#endif
303
304/*
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.
308 */
309#ifndef FRONTEND
310
311/*
312 * For callers that just need the XID part of the next transaction ID.
313 */
314static inline TransactionId
316{
318}
319
320/* return transaction ID backed up by amount, handling wraparound correctly */
321static inline TransactionId
323{
324 xid -= amount;
325
326 while (xid < FirstNormalTransactionId)
327 xid--;
328
329 return xid;
330}
331
332/* return the older of the two IDs */
333static inline TransactionId
335{
337 return b;
338
340 return a;
341
343 return a;
344 return b;
345}
346
347/* return the older of the two IDs, assuming they're both normal */
348static inline TransactionId
350{
354 return a;
355 return b;
356}
357
358/* return the newer of the two IDs */
359static inline FullTransactionId
361{
363 return b;
364
366 return a;
367
369 return a;
370 return b;
371}
372
373/*
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.
379 */
380static inline FullTransactionId
382 TransactionId xid)
383{
385
386 /* Special transaction ID. */
387 if (!TransactionIdIsNormal(xid))
389
391 XidFromFullTransactionId(nextFullXid)));
392
393 /*
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
398 * ahead of it.
399 *
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.
405 */
406 epoch = EpochFromFullTransactionId(nextFullXid);
407 if (unlikely(xid > XidFromFullTransactionId(nextFullXid)))
408 {
409 Assert(epoch != 0);
410 epoch--;
411 }
412
414}
415
416#endif /* FRONTEND */
417
418#endif /* TRANSAM_H */
#define PGDLLIMPORT
Definition: c.h:1291
uint64_t uint64
Definition: c.h:503
#define unlikely(x)
Definition: c.h:347
uint32_t uint32
Definition: c.h:502
uint32 TransactionId
Definition: c.h:623
size_t Size
Definition: c.h:576
Assert(PointerIsAligned(start, uint64))
static struct @165 value
int b
Definition: isn.c:74
int a
Definition: isn.c:73
unsigned int Oid
Definition: postgres_ext.h:30
uint64 value
Definition: transam.h:67
TransactionId xidStopLimit
Definition: transam.h:225
TransactionId oldestCommitTsXid
Definition: transam.h:232
TransactionId newestCommitTsXid
Definition: transam.h:233
TransactionId xidWarnLimit
Definition: transam.h:224
TransactionId xidWrapLimit
Definition: transam.h:226
FullTransactionId latestCompletedXid
Definition: transam.h:238
FullTransactionId nextXid
Definition: transam.h:220
TransactionId xidVacLimit
Definition: transam.h:223
uint64 xactCompletionCount
Definition: transam.h:248
TransactionId oldestClogXid
Definition: transam.h:253
TransactionId oldestXid
Definition: transam.h:222
void TransactionIdAsyncCommitTree(TransactionId xid, int nxids, TransactionId *xids, XLogRecPtr lsn)
Definition: transam.c:252
PGDLLIMPORT TransamVariablesData * TransamVariables
Definition: varsup.c:34
FullTransactionId ReadNextFullTransactionId(void)
Definition: varsup.c:288
void AdvanceNextFullTransactionIdPastXid(TransactionId xid)
Definition: varsup.c:304
Oid GetNewObjectId(void)
Definition: varsup.c:555
static TransactionId ReadNextTransactionId(void)
Definition: transam.h:315
static TransactionId TransactionIdRetreatedBy(TransactionId xid, uint32 amount)
Definition: transam.h:322
static FullTransactionId FullTransactionIdNewer(FullTransactionId a, FullTransactionId b)
Definition: transam.h:360
TransactionId TransactionIdLatest(TransactionId mainxid, int nxids, const TransactionId *xids)
Definition: transam.c:345
static FullTransactionId FullTransactionIdFromAllowableAt(FullTransactionId nextFullXid, TransactionId xid)
Definition: transam.h:381
static void FullTransactionIdRetreat(FullTransactionId *dest)
Definition: transam.h:103
#define EpochFromFullTransactionId(x)
Definition: transam.h:47
bool TransactionStartedDuringRecovery(void)
Definition: xact.c:1042
static FullTransactionId FullTransactionIdFromU64(uint64 value)
Definition: transam.h:81
void SetTransactionIdLimit(TransactionId oldest_datfrozenxid, Oid oldest_datoid)
Definition: varsup.c:372
#define AssertTransactionIdInAllowableRange(xid)
Definition: transam.h:301
bool TransactionIdDidCommit(TransactionId transactionId)
Definition: transam.c:126
void TransactionIdCommitTree(TransactionId xid, int nxids, TransactionId *xids)
Definition: transam.c:240
static TransactionId NormalTransactionIdOlder(TransactionId a, TransactionId b)
Definition: transam.h:349
Size VarsupShmemSize(void)
Definition: varsup.c:41
FullTransactionId GetNewTransactionId(bool isSubXact)
Definition: varsup.c:77
#define NormalTransactionIdPrecedes(id1, id2)
Definition: transam.h:147
void StopGeneratingPinnedObjectIds(void)
Definition: varsup.c:652
void TransactionIdAbortTree(TransactionId xid, int nxids, TransactionId *xids)
Definition: transam.c:270
bool TransactionIdPrecedes(TransactionId id1, TransactionId id2)
Definition: transam.c:280
bool ForceTransactionIdLimitUpdate(void)
Definition: varsup.c:517
#define FullTransactionIdFollows(a, b)
Definition: transam.h:53
#define XidFromFullTransactionId(x)
Definition: transam.h:48
bool TransactionIdPrecedesOrEquals(TransactionId id1, TransactionId id2)
Definition: transam.c:299
bool TransactionIdDidAbort(TransactionId transactionId)
Definition: transam.c:188
bool TransactionIdFollows(TransactionId id1, TransactionId id2)
Definition: transam.c:314
XLogRecPtr TransactionIdGetCommitLSN(TransactionId xid)
Definition: transam.c:382
void AdvanceOldestClogXid(TransactionId oldest_datfrozenxid)
Definition: varsup.c:355
#define FirstNormalTransactionId
Definition: transam.h:34
static void FullTransactionIdAdvance(FullTransactionId *dest)
Definition: transam.h:128
struct TransamVariablesData TransamVariablesData
#define TransactionIdIsValid(xid)
Definition: transam.h:41
static FullTransactionId FullTransactionIdFromEpochAndXid(uint32 epoch, TransactionId xid)
Definition: transam.h:71
struct FullTransactionId FullTransactionId
#define TransactionIdIsNormal(xid)
Definition: transam.h:42
#define FirstNormalFullTransactionId
Definition: transam.h:57
#define FullTransactionIdPrecedes(a, b)
Definition: transam.h:51
#define FullTransactionIdIsValid(x)
Definition: transam.h:55
static TransactionId TransactionIdOlder(TransactionId a, TransactionId b)
Definition: transam.h:334
void VarsupShmemInit(void)
Definition: varsup.c:47
bool TransactionIdFollowsOrEquals(TransactionId id1, TransactionId id2)
Definition: transam.c:329
static const unsigned __int64 epoch
uint64 XLogRecPtr
Definition: xlogdefs.h:21