Line data Source code
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 : */
65 : typedef struct FullTransactionId
66 : {
67 : uint64 value;
68 : } FullTransactionId;
69 :
70 : static inline FullTransactionId
71 53159502 : FullTransactionIdFromEpochAndXid(uint32 epoch, TransactionId xid)
72 : {
73 : FullTransactionId result;
74 :
75 53159502 : result.value = ((uint64) epoch) << 32 | xid;
76 :
77 53159502 : return result;
78 : }
79 :
80 : static inline FullTransactionId
81 23612444 : FullTransactionIdFromU64(uint64 value)
82 : {
83 : FullTransactionId result;
84 :
85 23612444 : result.value = value;
86 :
87 23612444 : 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 : */
102 : static inline void
103 2014 : FullTransactionIdRetreat(FullTransactionId *dest)
104 : {
105 2014 : 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 : */
112 2014 : if (FullTransactionIdPrecedes(*dest, FirstNormalFullTransactionId))
113 200 : return;
114 :
115 : /*
116 : * But we do need to step over XIDs that'd appear special only for 32bit
117 : * XIDs.
118 : */
119 1814 : while (XidFromFullTransactionId(*dest) < FirstNormalTransactionId)
120 0 : 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 : */
127 : static inline void
128 49687980 : FullTransactionIdAdvance(FullTransactionId *dest)
129 : {
130 49687980 : dest->value++;
131 :
132 : /* see FullTransactionIdAdvance() */
133 49687980 : if (FullTransactionIdPrecedes(*dest, FirstNormalFullTransactionId))
134 0 : return;
135 :
136 49687992 : while (XidFromFullTransactionId(*dest) < FirstNormalTransactionId)
137 12 : 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 : */
209 : typedef struct TransamVariablesData
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 : */
232 : TransactionId oldestCommitTsXid;
233 : TransactionId newestCommitTsXid;
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 : */
248 : uint64 xactCompletionCount;
249 :
250 : /*
251 : * These fields are protected by XactTruncationLock
252 : */
253 : TransactionId oldestClogXid; /* oldest it's safe to look up in clog */
254 :
255 : } TransamVariablesData;
256 :
257 :
258 :
259 : /*
260 : * TransactionIdPrecedes --- is id1 logically < id2?
261 : */
262 : static inline bool
263 358780316 : TransactionIdPrecedes(TransactionId id1, TransactionId id2)
264 : {
265 : /*
266 : * If either ID is a permanent XID then we can just do unsigned
267 : * comparison. If both are normal, do a modulo-2^32 comparison.
268 : */
269 : int32 diff;
270 :
271 358780316 : if (!TransactionIdIsNormal(id1) || !TransactionIdIsNormal(id2))
272 94914520 : return (id1 < id2);
273 :
274 263865796 : diff = (int32) (id1 - id2);
275 263865796 : return (diff < 0);
276 : }
277 :
278 : /*
279 : * TransactionIdPrecedesOrEquals --- is id1 logically <= id2?
280 : */
281 : static inline bool
282 266156 : TransactionIdPrecedesOrEquals(TransactionId id1, TransactionId id2)
283 : {
284 : int32 diff;
285 :
286 266156 : if (!TransactionIdIsNormal(id1) || !TransactionIdIsNormal(id2))
287 2322 : return (id1 <= id2);
288 :
289 263834 : diff = (int32) (id1 - id2);
290 263834 : return (diff <= 0);
291 : }
292 :
293 : /*
294 : * TransactionIdFollows --- is id1 logically > id2?
295 : */
296 : static inline bool
297 51571166 : TransactionIdFollows(TransactionId id1, TransactionId id2)
298 : {
299 : int32 diff;
300 :
301 51571166 : if (!TransactionIdIsNormal(id1) || !TransactionIdIsNormal(id2))
302 24025052 : return (id1 > id2);
303 :
304 27546114 : diff = (int32) (id1 - id2);
305 27546114 : return (diff > 0);
306 : }
307 :
308 : /*
309 : * TransactionIdFollowsOrEquals --- is id1 logically >= id2?
310 : */
311 : static inline bool
312 103450890 : TransactionIdFollowsOrEquals(TransactionId id1, TransactionId id2)
313 : {
314 : int32 diff;
315 :
316 103450890 : if (!TransactionIdIsNormal(id1) || !TransactionIdIsNormal(id2))
317 106776 : return (id1 >= id2);
318 :
319 103344114 : diff = (int32) (id1 - id2);
320 103344114 : return (diff >= 0);
321 : }
322 :
323 :
324 : /* ----------------
325 : * extern declarations
326 : * ----------------
327 : */
328 :
329 : /* in transam/xact.c */
330 : extern bool TransactionStartedDuringRecovery(void);
331 :
332 : /* in transam/varsup.c */
333 : extern PGDLLIMPORT TransamVariablesData *TransamVariables;
334 :
335 : /*
336 : * prototypes for functions in transam/transam.c
337 : */
338 : extern bool TransactionIdDidCommit(TransactionId transactionId);
339 : extern bool TransactionIdDidAbort(TransactionId transactionId);
340 : extern void TransactionIdCommitTree(TransactionId xid, int nxids, TransactionId *xids);
341 : extern void TransactionIdAsyncCommitTree(TransactionId xid, int nxids, TransactionId *xids, XLogRecPtr lsn);
342 : extern void TransactionIdAbortTree(TransactionId xid, int nxids, TransactionId *xids);
343 : extern TransactionId TransactionIdLatest(TransactionId mainxid,
344 : int nxids, const TransactionId *xids);
345 : extern XLogRecPtr TransactionIdGetCommitLSN(TransactionId xid);
346 :
347 : /* in transam/varsup.c */
348 : extern Size VarsupShmemSize(void);
349 : extern void VarsupShmemInit(void);
350 : extern FullTransactionId GetNewTransactionId(bool isSubXact);
351 : extern void AdvanceNextFullTransactionIdPastXid(TransactionId xid);
352 : extern FullTransactionId ReadNextFullTransactionId(void);
353 : extern void SetTransactionIdLimit(TransactionId oldest_datfrozenxid,
354 : Oid oldest_datoid);
355 : extern void AdvanceOldestClogXid(TransactionId oldest_datfrozenxid);
356 : extern bool ForceTransactionIdLimitUpdate(void);
357 : extern Oid GetNewObjectId(void);
358 : extern void StopGeneratingPinnedObjectIds(void);
359 :
360 : #ifdef USE_ASSERT_CHECKING
361 : extern void AssertTransactionIdInAllowableRange(TransactionId xid);
362 : #else
363 : #define AssertTransactionIdInAllowableRange(xid) ((void)true)
364 : #endif
365 :
366 : /*
367 : * Some frontend programs include this header. For compilers that emit static
368 : * inline functions even when they're unused, that leads to unsatisfied
369 : * external references; hence hide them with #ifndef FRONTEND.
370 : */
371 : #ifndef FRONTEND
372 :
373 : /*
374 : * For callers that just need the XID part of the next transaction ID.
375 : */
376 : static inline TransactionId
377 769850 : ReadNextTransactionId(void)
378 : {
379 769850 : return XidFromFullTransactionId(ReadNextFullTransactionId());
380 : }
381 :
382 : /* return transaction ID backed up by amount, handling wraparound correctly */
383 : static inline TransactionId
384 : TransactionIdRetreatedBy(TransactionId xid, uint32 amount)
385 : {
386 : xid -= amount;
387 :
388 : while (xid < FirstNormalTransactionId)
389 : xid--;
390 :
391 : return xid;
392 : }
393 :
394 : /* return the older of the two IDs */
395 : static inline TransactionId
396 9866884 : TransactionIdOlder(TransactionId a, TransactionId b)
397 : {
398 9866884 : if (!TransactionIdIsValid(a))
399 1901394 : return b;
400 :
401 7965490 : if (!TransactionIdIsValid(b))
402 3226686 : return a;
403 :
404 4738804 : if (TransactionIdPrecedes(a, b))
405 690806 : return a;
406 4047998 : return b;
407 : }
408 :
409 : /* return the older of the two IDs, assuming they're both normal */
410 : static inline TransactionId
411 : NormalTransactionIdOlder(TransactionId a, TransactionId b)
412 : {
413 : Assert(TransactionIdIsNormal(a));
414 : Assert(TransactionIdIsNormal(b));
415 : if (NormalTransactionIdPrecedes(a, b))
416 : return a;
417 : return b;
418 : }
419 :
420 : /* return the newer of the two IDs */
421 : static inline FullTransactionId
422 5840862 : FullTransactionIdNewer(FullTransactionId a, FullTransactionId b)
423 : {
424 5840862 : if (!FullTransactionIdIsValid(a))
425 109212 : return b;
426 :
427 5731650 : if (!FullTransactionIdIsValid(b))
428 112470 : return a;
429 :
430 5619180 : if (FullTransactionIdFollows(a, b))
431 2693708 : return a;
432 2925472 : return b;
433 : }
434 :
435 : /*
436 : * Compute FullTransactionId for the given TransactionId, assuming xid was
437 : * between [oldestXid, nextXid] at the time when TransamVariables->nextXid was
438 : * nextFullXid. When adding calls, evaluate what prevents xid from preceding
439 : * oldestXid if SetTransactionIdLimit() runs between the collection of xid and
440 : * the collection of nextFullXid.
441 : */
442 : static inline FullTransactionId
443 10054 : FullTransactionIdFromAllowableAt(FullTransactionId nextFullXid,
444 : TransactionId xid)
445 : {
446 : uint32 epoch;
447 :
448 : /* Special transaction ID. */
449 10054 : if (!TransactionIdIsNormal(xid))
450 0 : return FullTransactionIdFromEpochAndXid(0, xid);
451 :
452 : Assert(TransactionIdPrecedesOrEquals(xid,
453 : XidFromFullTransactionId(nextFullXid)));
454 :
455 : /*
456 : * The 64 bit result must be <= nextFullXid, since nextFullXid hadn't been
457 : * issued yet when xid was in the past. The xid must therefore be from
458 : * the epoch of nextFullXid or the epoch before. We know this because we
459 : * must remove (by freezing) an XID before assigning the XID half an epoch
460 : * ahead of it.
461 : *
462 : * The unlikely() branch hint is dubious. It's perfect for the first 2^32
463 : * XIDs of a cluster's life. Right at 2^32 XIDs, misprediction shoots to
464 : * 100%, then improves until perfection returns 2^31 XIDs later. Since
465 : * current callers pass relatively-recent XIDs, expect >90% prediction
466 : * accuracy overall. This favors average latency over tail latency.
467 : */
468 10054 : epoch = EpochFromFullTransactionId(nextFullXid);
469 10054 : if (unlikely(xid > XidFromFullTransactionId(nextFullXid)))
470 : {
471 : Assert(epoch != 0);
472 0 : epoch--;
473 : }
474 :
475 10054 : return FullTransactionIdFromEpochAndXid(epoch, xid);
476 : }
477 :
478 : #endif /* FRONTEND */
479 :
480 : #endif /* TRANSAM_H */
|
