PostgreSQL Source Code  git master
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-2021, 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;
69 
70 static inline FullTransactionId
72 {
73  FullTransactionId result;
74 
75  result.value = ((uint64) epoch) << 32 | xid;
76 
77  return result;
78 }
79 
80 static 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  */
102 static 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  */
127 static 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  * VariableCache 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 VariableCacheData
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 
258 
259 
260 /* ----------------
261  * extern declarations
262  * ----------------
263  */
264 
265 /* in transam/xact.c */
266 extern bool TransactionStartedDuringRecovery(void);
267 
268 /* in transam/varsup.c */
270 
271 /*
272  * prototypes for functions in transam/transam.c
273  */
274 extern bool TransactionIdDidCommit(TransactionId transactionId);
275 extern bool TransactionIdDidAbort(TransactionId transactionId);
276 extern bool TransactionIdIsKnownCompleted(TransactionId transactionId);
277 extern void TransactionIdCommitTree(TransactionId xid, int nxids, TransactionId *xids);
278 extern void TransactionIdAsyncCommitTree(TransactionId xid, int nxids, TransactionId *xids, XLogRecPtr lsn);
279 extern void TransactionIdAbortTree(TransactionId xid, int nxids, TransactionId *xids);
282 extern bool TransactionIdFollows(TransactionId id1, TransactionId id2);
285  int nxids, const TransactionId *xids);
287 
288 /* in transam/varsup.c */
289 extern FullTransactionId GetNewTransactionId(bool isSubXact);
292 extern void SetTransactionIdLimit(TransactionId oldest_datfrozenxid,
293  Oid oldest_datoid);
294 extern void AdvanceOldestClogXid(TransactionId oldest_datfrozenxid);
295 extern bool ForceTransactionIdLimitUpdate(void);
296 extern Oid GetNewObjectId(void);
297 extern void StopGeneratingPinnedObjectIds(void);
298 
299 #ifdef USE_ASSERT_CHECKING
301 #else
302 #define AssertTransactionIdInAllowableRange(xid) ((void)true)
303 #endif
304 
305 /*
306  * Some frontend programs include this header. For compilers that emit static
307  * inline functions even when they're unused, that leads to unsatisfied
308  * external references; hence hide them with #ifndef FRONTEND.
309  */
310 #ifndef FRONTEND
311 
312 /*
313  * For callers that just need the XID part of the next transaction ID.
314  */
315 static inline TransactionId
317 {
319 }
320 
321 /* return transaction ID backed up by amount, handling wraparound correctly */
322 static inline TransactionId
324 {
325  xid -= amount;
326 
327  while (xid < FirstNormalTransactionId)
328  xid--;
329 
330  return xid;
331 }
332 
333 /* return the older of the two IDs */
334 static inline TransactionId
336 {
337  if (!TransactionIdIsValid(a))
338  return b;
339 
340  if (!TransactionIdIsValid(b))
341  return a;
342 
343  if (TransactionIdPrecedes(a, b))
344  return a;
345  return b;
346 }
347 
348 /* return the older of the two IDs, assuming they're both normal */
349 static inline TransactionId
351 {
355  return a;
356  return b;
357 }
358 
359 /* return the newer of the two IDs */
360 static inline FullTransactionId
362 {
364  return b;
365 
367  return a;
368 
370  return a;
371  return b;
372 }
373 
374 #endif /* FRONTEND */
375 
376 #endif /* TRANSAM_H */
unsigned int uint32
Definition: c.h:441
#define PGDLLIMPORT
Definition: c.h:1318
uint32 TransactionId
Definition: c.h:587
static const unsigned __int64 epoch
Definition: gettimeofday.c:34
static struct @142 value
int b
Definition: isn.c:70
int a
Definition: isn.c:69
Assert(fmt[strlen(fmt) - 1] !='\n')
unsigned int Oid
Definition: postgres_ext.h:31
uint64 value
Definition: transam.h:67
FullTransactionId nextXid
Definition: transam.h:220
TransactionId xidWrapLimit
Definition: transam.h:226
TransactionId newestCommitTsXid
Definition: transam.h:233
uint64 xactCompletionCount
Definition: transam.h:248
TransactionId oldestXid
Definition: transam.h:222
TransactionId oldestCommitTsXid
Definition: transam.h:232
TransactionId xidWarnLimit
Definition: transam.h:224
TransactionId oldestClogXid
Definition: transam.h:253
uint32 oidCount
Definition: transam.h:215
TransactionId xidStopLimit
Definition: transam.h:225
FullTransactionId latestCompletedXid
Definition: transam.h:238
TransactionId xidVacLimit
Definition: transam.h:223
void TransactionIdAsyncCommitTree(TransactionId xid, int nxids, TransactionId *xids, XLogRecPtr lsn)
Definition: transam.c:272
FullTransactionId ReadNextFullTransactionId(void)
Definition: varsup.c:261
void AdvanceNextFullTransactionIdPastXid(TransactionId xid)
Definition: varsup.c:277
Oid GetNewObjectId(void)
Definition: varsup.c:528
static TransactionId ReadNextTransactionId(void)
Definition: transam.h:316
static TransactionId TransactionIdRetreatedBy(TransactionId xid, uint32 amount)
Definition: transam.h:323
static FullTransactionId FullTransactionIdNewer(FullTransactionId a, FullTransactionId b)
Definition: transam.h:361
struct VariableCacheData VariableCacheData
TransactionId TransactionIdLatest(TransactionId mainxid, int nxids, const TransactionId *xids)
Definition: transam.c:365
bool TransactionIdIsKnownCompleted(TransactionId transactionId)
Definition: transam.c:238
static void FullTransactionIdRetreat(FullTransactionId *dest)
Definition: transam.h:103
bool TransactionStartedDuringRecovery(void)
Definition: xact.c:1022
static FullTransactionId FullTransactionIdFromU64(uint64 value)
Definition: transam.h:81
PGDLLIMPORT VariableCache ShmemVariableCache
Definition: varsup.c:34
void SetTransactionIdLimit(TransactionId oldest_datfrozenxid, Oid oldest_datoid)
Definition: varsup.c:345
#define AssertTransactionIdInAllowableRange(xid)
Definition: transam.h:302
bool TransactionIdDidCommit(TransactionId transactionId)
Definition: transam.c:125
void TransactionIdCommitTree(TransactionId xid, int nxids, TransactionId *xids)
Definition: transam.c:260
static TransactionId NormalTransactionIdOlder(TransactionId a, TransactionId b)
Definition: transam.h:350
FullTransactionId GetNewTransactionId(bool isSubXact)
Definition: varsup.c:50
#define NormalTransactionIdPrecedes(id1, id2)
Definition: transam.h:147
void StopGeneratingPinnedObjectIds(void)
Definition: varsup.c:625
void TransactionIdAbortTree(TransactionId xid, int nxids, TransactionId *xids)
Definition: transam.c:290
bool TransactionIdPrecedes(TransactionId id1, TransactionId id2)
Definition: transam.c:300
bool ForceTransactionIdLimitUpdate(void)
Definition: varsup.c:490
#define FullTransactionIdFollows(a, b)
Definition: transam.h:53
#define XidFromFullTransactionId(x)
Definition: transam.h:48
bool TransactionIdPrecedesOrEquals(TransactionId id1, TransactionId id2)
Definition: transam.c:319
bool TransactionIdDidAbort(TransactionId transactionId)
Definition: transam.c:181
bool TransactionIdFollows(TransactionId id1, TransactionId id2)
Definition: transam.c:334
XLogRecPtr TransactionIdGetCommitLSN(TransactionId xid)
Definition: transam.c:402
void AdvanceOldestClogXid(TransactionId oldest_datfrozenxid)
Definition: varsup.c:328
#define FirstNormalTransactionId
Definition: transam.h:34
static void FullTransactionIdAdvance(FullTransactionId *dest)
Definition: transam.h:128
#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:335
bool TransactionIdFollowsOrEquals(TransactionId id1, TransactionId id2)
Definition: transam.c:349
VariableCacheData * VariableCache
Definition: transam.h:257
uint64 XLogRecPtr
Definition: xlogdefs.h:21