Branch data Line data Source code
1 : : /*-------------------------------------------------------------------------
2 : : *
3 : : * transam.h
4 : : * postgres transaction access method support code
5 : : *
6 : : *
7 : : * Portions Copyright (c) 1996-2026, 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 : 26994910 : FullTransactionIdFromEpochAndXid(uint32 epoch, TransactionId xid)
72 : : {
73 : : FullTransactionId result;
74 : :
75 : 26994910 : result.value = ((uint64) epoch) << 32 | xid;
76 : :
77 : 26994910 : return result;
78 : : }
79 : :
80 : : static inline FullTransactionId
81 : 10765704 : FullTransactionIdFromU64(uint64 value)
82 : : {
83 : : FullTransactionId result;
84 : :
85 : 10765704 : result.value = value;
86 : :
87 : 10765704 : 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 : 1194 : FullTransactionIdRetreat(FullTransactionId *dest)
104 : : {
105 : 1194 : 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 [ + + ]: 1194 : if (FullTransactionIdPrecedes(*dest, FirstNormalFullTransactionId))
113 : 118 : return;
114 : :
115 : : /*
116 : : * But we do need to step over XIDs that'd appear special only for 32bit
117 : : * XIDs.
118 : : */
119 [ - + ]: 1076 : 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 : 24981936 : FullTransactionIdAdvance(FullTransactionId *dest)
129 : : {
130 : 24981936 : dest->value++;
131 : :
132 : : /* see FullTransactionIdAdvance() */
133 [ - + ]: 24981936 : if (FullTransactionIdPrecedes(*dest, FirstNormalFullTransactionId))
134 : 0 : return;
135 : :
136 [ + + ]: 24981942 : while (XidFromFullTransactionId(*dest) < FirstNormalTransactionId)
137 : 6 : 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: the OID generator is 8 bytes wide (see GetNewObjectId8()). For
190 : : * its lower 4 bytes, we skip over OIDs 0-16383 and resume with 16384.
191 : : * This minimizes the odds of OID conflict when using GetNewObjectId(), by not
192 : : * reassigning OIDs that might have been assigned during initdb. Critically,
193 : : * it also ensures that no user-created object will be considered pinned.
194 : : * ----------
195 : : */
196 : : #define FirstGenbkiObjectId 10000
197 : : #define FirstUnpinnedObjectId 12000
198 : : #define FirstNormalObjectId 16384
199 : :
200 : : /*
201 : : * TransamVariables is a data structure in shared memory that is used to track
202 : : * OID and XID assignment state. For largely historical reasons, there is
203 : : * just one struct with different fields that are protected by different
204 : : * LWLocks.
205 : : *
206 : : * Note: xidWrapLimit and oldestXidDB are not "active" values, but are
207 : : * used just to generate useful messages when xidWarnLimit or xidStopLimit
208 : : * are exceeded.
209 : : */
210 : : typedef struct TransamVariablesData
211 : : {
212 : : /*
213 : : * These fields are protected by OidGenLock.
214 : : */
215 : : Oid8 nextOid; /* next OID (8 bytes) to assign */
216 : : uint32 oidCount; /* OIDs available before must do XLOG work */
217 : :
218 : : /*
219 : : * These fields are protected by XidGenLock.
220 : : */
221 : : FullTransactionId nextXid; /* next XID to assign */
222 : :
223 : : TransactionId oldestXid; /* cluster-wide minimum datfrozenxid */
224 : : TransactionId xidVacLimit; /* start forcing autovacuums here */
225 : : TransactionId xidWarnLimit; /* start complaining here */
226 : : TransactionId xidStopLimit; /* refuse to advance nextXid beyond here */
227 : : TransactionId xidWrapLimit; /* where the world ends */
228 : : Oid oldestXidDB; /* database with minimum datfrozenxid */
229 : :
230 : : /*
231 : : * These fields are protected by CommitTsLock
232 : : */
233 : : TransactionId oldestCommitTsXid;
234 : : TransactionId newestCommitTsXid;
235 : :
236 : : /*
237 : : * These fields are protected by ProcArrayLock.
238 : : */
239 : : FullTransactionId latestCompletedXid; /* newest full XID that has
240 : : * committed or aborted */
241 : :
242 : : /*
243 : : * Number of top-level transactions with xids (i.e. which may have
244 : : * modified the database) that completed in some form since the start of
245 : : * the server. This currently is solely used to check whether
246 : : * GetSnapshotData() needs to recompute the contents of the snapshot, or
247 : : * not. There are likely other users of this. Always above 1.
248 : : */
249 : : uint64 xactCompletionCount;
250 : :
251 : : /*
252 : : * These fields are protected by XactTruncationLock
253 : : */
254 : : TransactionId oldestClogXid; /* oldest it's safe to look up in clog */
255 : :
256 : : } TransamVariablesData;
257 : :
258 : :
259 : :
260 : : /*
261 : : * TransactionIdPrecedes --- is id1 logically < id2?
262 : : */
263 : : static inline bool
264 : 194699921 : TransactionIdPrecedes(TransactionId id1, TransactionId id2)
265 : : {
266 : : /*
267 : : * If either ID is a permanent XID then we can just do unsigned
268 : : * comparison. If both are normal, do a modulo-2^32 comparison.
269 : : */
270 : : int32 diff;
271 : :
272 [ + + + + ]: 194699921 : if (!TransactionIdIsNormal(id1) || !TransactionIdIsNormal(id2))
273 : 42071456 : return (id1 < id2);
274 : :
275 : 152628465 : diff = (int32) (id1 - id2);
276 : 152628465 : return (diff < 0);
277 : : }
278 : :
279 : : /*
280 : : * TransactionIdPrecedesOrEquals --- is id1 logically <= id2?
281 : : */
282 : : static inline bool
283 : 129516 : TransactionIdPrecedesOrEquals(TransactionId id1, TransactionId id2)
284 : : {
285 : : int32 diff;
286 : :
287 [ + - + + ]: 129516 : if (!TransactionIdIsNormal(id1) || !TransactionIdIsNormal(id2))
288 : 1731 : return (id1 <= id2);
289 : :
290 : 127785 : diff = (int32) (id1 - id2);
291 : 127785 : return (diff <= 0);
292 : : }
293 : :
294 : : /*
295 : : * TransactionIdFollows --- is id1 logically > id2?
296 : : */
297 : : static inline bool
298 : 37088212 : TransactionIdFollows(TransactionId id1, TransactionId id2)
299 : : {
300 : : int32 diff;
301 : :
302 [ + + + + ]: 37088212 : if (!TransactionIdIsNormal(id1) || !TransactionIdIsNormal(id2))
303 : 4635529 : return (id1 > id2);
304 : :
305 : 32452683 : diff = (int32) (id1 - id2);
306 : 32452683 : return (diff > 0);
307 : : }
308 : :
309 : : /*
310 : : * TransactionIdFollowsOrEquals --- is id1 logically >= id2?
311 : : */
312 : : static inline bool
313 : 55726451 : TransactionIdFollowsOrEquals(TransactionId id1, TransactionId id2)
314 : : {
315 : : int32 diff;
316 : :
317 [ + + - + ]: 55726451 : if (!TransactionIdIsNormal(id1) || !TransactionIdIsNormal(id2))
318 : 64037 : return (id1 >= id2);
319 : :
320 : 55662414 : diff = (int32) (id1 - id2);
321 : 55662414 : return (diff >= 0);
322 : : }
323 : :
324 : :
325 : : /* ----------------
326 : : * extern declarations
327 : : * ----------------
328 : : */
329 : :
330 : : /* in transam/xact.c */
331 : : extern bool TransactionStartedDuringRecovery(void);
332 : :
333 : : /* in transam/varsup.c */
334 : : extern PGDLLIMPORT TransamVariablesData *TransamVariables;
335 : :
336 : : /*
337 : : * prototypes for functions in transam/transam.c
338 : : */
339 : : extern bool TransactionIdDidCommit(TransactionId transactionId);
340 : : extern bool TransactionIdDidAbort(TransactionId transactionId);
341 : : extern void TransactionIdCommitTree(TransactionId xid, int nxids, TransactionId *xids);
342 : : extern void TransactionIdAsyncCommitTree(TransactionId xid, int nxids, TransactionId *xids, XLogRecPtr lsn);
343 : : extern void TransactionIdAbortTree(TransactionId xid, int nxids, TransactionId *xids);
344 : : extern TransactionId TransactionIdLatest(TransactionId mainxid,
345 : : int nxids, const TransactionId *xids);
346 : : extern XLogRecPtr TransactionIdGetCommitLSN(TransactionId xid);
347 : :
348 : : /* in transam/varsup.c */
349 : : extern FullTransactionId GetNewTransactionId(bool isSubXact);
350 : : extern void AdvanceNextFullTransactionIdPastXid(TransactionId xid);
351 : : extern FullTransactionId ReadNextFullTransactionId(void);
352 : : extern void SetTransactionIdLimit(TransactionId oldest_datfrozenxid,
353 : : Oid oldest_datoid);
354 : : extern void AdvanceOldestClogXid(TransactionId oldest_datfrozenxid);
355 : : extern bool ForceTransactionIdLimitUpdate(void);
356 : : extern Oid GetNewObjectId(void);
357 : : extern Oid8 GetNewObjectId8(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 : 366750 : ReadNextTransactionId(void)
378 : : {
379 : 366750 : 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 : 5433845 : TransactionIdOlder(TransactionId a, TransactionId b)
397 : : {
398 [ + + ]: 5433845 : if (!TransactionIdIsValid(a))
399 : 1169968 : return b;
400 : :
401 [ + + ]: 4263877 : if (!TransactionIdIsValid(b))
402 : 1804746 : return a;
403 : :
404 [ + + ]: 2459131 : if (TransactionIdPrecedes(a, b))
405 : 327265 : return a;
406 : 2131866 : 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 : 3642498 : FullTransactionIdNewer(FullTransactionId a, FullTransactionId b)
423 : : {
424 [ + + ]: 3642498 : if (!FullTransactionIdIsValid(a))
425 : 63762 : return b;
426 : :
427 [ + + ]: 3578736 : if (!FullTransactionIdIsValid(b))
428 : 65775 : return a;
429 : :
430 [ + + ]: 3512961 : if (FullTransactionIdFollows(a, b))
431 : 1839665 : return a;
432 : 1673296 : 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 : 10772 : FullTransactionIdFromAllowableAt(FullTransactionId nextFullXid,
444 : : TransactionId xid)
445 : : {
446 : : uint32 epoch;
447 : :
448 : : /* Special transaction ID. */
449 [ - + ]: 10772 : 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 : 10772 : epoch = EpochFromFullTransactionId(nextFullXid);
469 [ - + ]: 10772 : if (unlikely(xid > XidFromFullTransactionId(nextFullXid)))
470 : : {
471 : : Assert(epoch != 0);
472 : 0 : epoch--;
473 : : }
474 : :
475 : 10772 : return FullTransactionIdFromEpochAndXid(epoch, xid);
476 : : }
477 : :
478 : : #endif /* FRONTEND */
479 : :
480 : : #endif /* TRANSAM_H */
|
