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.
169  *
170  * OIDS 12000-16383 are reserved for assignment during initdb
171  * using the OID generator. (We start the generator at 12000.)
172  *
173  * OIDs beginning at 16384 are assigned from the OID generator
174  * during normal multiuser operation. (We force the generator up to
175  * 16384 as soon as we are in normal operation.)
176  *
177  * The choices of 8000, 10000 and 12000 are completely arbitrary, and can be
178  * moved if we run low on OIDs in any category. Changing the macros below,
179  * and updating relevant documentation (see bki.sgml and RELEASE_CHANGES),
180  * should be sufficient to do this. Moving the 16384 boundary between
181  * initdb-assigned OIDs and user-defined objects would be substantially
182  * more painful, however, since some user-defined OIDs will appear in
183  * on-disk data; such a change would probably break pg_upgrade.
184  *
185  * NOTE: if the OID generator wraps around, we skip over OIDs 0-16383
186  * and resume with 16384. This minimizes the odds of OID conflict, by not
187  * reassigning OIDs that might have been assigned during initdb.
188  * ----------
189  */
190 #define FirstGenbkiObjectId 10000
191 #define FirstBootstrapObjectId 12000
192 #define FirstNormalObjectId 16384
193 
194 /*
195  * VariableCache is a data structure in shared memory that is used to track
196  * OID and XID assignment state. For largely historical reasons, there is
197  * just one struct with different fields that are protected by different
198  * LWLocks.
199  *
200  * Note: xidWrapLimit and oldestXidDB are not "active" values, but are
201  * used just to generate useful messages when xidWarnLimit or xidStopLimit
202  * are exceeded.
203  */
204 typedef struct VariableCacheData
205 {
206  /*
207  * These fields are protected by OidGenLock.
208  */
209  Oid nextOid; /* next OID to assign */
210  uint32 oidCount; /* OIDs available before must do XLOG work */
211 
212  /*
213  * These fields are protected by XidGenLock.
214  */
215  FullTransactionId nextXid; /* next XID to assign */
216 
217  TransactionId oldestXid; /* cluster-wide minimum datfrozenxid */
218  TransactionId xidVacLimit; /* start forcing autovacuums here */
219  TransactionId xidWarnLimit; /* start complaining here */
220  TransactionId xidStopLimit; /* refuse to advance nextXid beyond here */
221  TransactionId xidWrapLimit; /* where the world ends */
222  Oid oldestXidDB; /* database with minimum datfrozenxid */
223 
224  /*
225  * These fields are protected by CommitTsLock
226  */
229 
230  /*
231  * These fields are protected by ProcArrayLock.
232  */
233  FullTransactionId latestCompletedXid; /* newest full XID that has
234  * committed or aborted */
235 
236  /*
237  * Number of top-level transactions with xids (i.e. which may have
238  * modified the database) that completed in some form since the start of
239  * the server. This currently is solely used to check whether
240  * GetSnapshotData() needs to recompute the contents of the snapshot, or
241  * not. There are likely other users of this. Always above 1.
242  */
244 
245  /*
246  * These fields are protected by XactTruncationLock
247  */
248  TransactionId oldestClogXid; /* oldest it's safe to look up in clog */
249 
251 
253 
254 
255 /* ----------------
256  * extern declarations
257  * ----------------
258  */
259 
260 /* in transam/xact.c */
261 extern bool TransactionStartedDuringRecovery(void);
262 
263 /* in transam/varsup.c */
265 
266 /*
267  * prototypes for functions in transam/transam.c
268  */
269 extern bool TransactionIdDidCommit(TransactionId transactionId);
270 extern bool TransactionIdDidAbort(TransactionId transactionId);
271 extern bool TransactionIdIsKnownCompleted(TransactionId transactionId);
272 extern void TransactionIdCommitTree(TransactionId xid, int nxids, TransactionId *xids);
273 extern void TransactionIdAsyncCommitTree(TransactionId xid, int nxids, TransactionId *xids, XLogRecPtr lsn);
274 extern void TransactionIdAbortTree(TransactionId xid, int nxids, TransactionId *xids);
277 extern bool TransactionIdFollows(TransactionId id1, TransactionId id2);
280  int nxids, const TransactionId *xids);
282 
283 /* in transam/varsup.c */
284 extern FullTransactionId GetNewTransactionId(bool isSubXact);
287 extern void SetTransactionIdLimit(TransactionId oldest_datfrozenxid,
288  Oid oldest_datoid);
289 extern void AdvanceOldestClogXid(TransactionId oldest_datfrozenxid);
290 extern bool ForceTransactionIdLimitUpdate(void);
291 extern Oid GetNewObjectId(void);
292 
293 #ifdef USE_ASSERT_CHECKING
295 #else
296 #define AssertTransactionIdInAllowableRange(xid) ((void)true)
297 #endif
298 
299 /*
300  * Some frontend programs include this header. For compilers that emit static
301  * inline functions even when they're unused, that leads to unsatisfied
302  * external references; hence hide them with #ifndef FRONTEND.
303  */
304 #ifndef FRONTEND
305 
306 /*
307  * For callers that just need the XID part of the next transaction ID.
308  */
309 static inline TransactionId
311 {
313 }
314 
315 /* return transaction ID backed up by amount, handling wraparound correctly */
316 static inline TransactionId
318 {
319  xid -= amount;
320 
321  while (xid < FirstNormalTransactionId)
322  xid--;
323 
324  return xid;
325 }
326 
327 /* return the older of the two IDs */
328 static inline TransactionId
330 {
331  if (!TransactionIdIsValid(a))
332  return b;
333 
334  if (!TransactionIdIsValid(b))
335  return a;
336 
337  if (TransactionIdPrecedes(a, b))
338  return a;
339  return b;
340 }
341 
342 /* return the older of the two IDs, assuming they're both normal */
343 static inline TransactionId
345 {
348  if (NormalTransactionIdPrecedes(a, b))
349  return a;
350  return b;
351 }
352 
353 /* return the newer of the two IDs */
354 static inline FullTransactionId
356 {
357  if (!FullTransactionIdIsValid(a))
358  return b;
359 
360  if (!FullTransactionIdIsValid(b))
361  return a;
362 
363  if (FullTransactionIdFollows(a, b))
364  return a;
365  return b;
366 }
367 
368 #endif /* FRONTEND */
369 
370 #endif /* TRANSAM_H */
void AdvanceNextFullTransactionIdPastXid(TransactionId xid)
Definition: varsup.c:277
VariableCacheData * VariableCache
Definition: transam.h:252
TransactionId TransactionIdLatest(TransactionId mainxid, int nxids, const TransactionId *xids)
Definition: transam.c:365
void SetTransactionIdLimit(TransactionId oldest_datfrozenxid, Oid oldest_datoid)
Definition: varsup.c:345
void TransactionIdAbortTree(TransactionId xid, int nxids, TransactionId *xids)
Definition: transam.c:290
uint32 TransactionId
Definition: c.h:587
uint32 oidCount
Definition: transam.h:210
FullTransactionId GetNewTransactionId(bool isSubXact)
Definition: varsup.c:50
#define FullTransactionIdIsValid(x)
Definition: transam.h:55
PGDLLIMPORT VariableCache ShmemVariableCache
Definition: varsup.c:34
TransactionId oldestXid
Definition: transam.h:217
static void FullTransactionIdRetreat(FullTransactionId *dest)
Definition: transam.h:103
uint64 xactCompletionCount
Definition: transam.h:243
bool TransactionIdFollows(TransactionId id1, TransactionId id2)
Definition: transam.c:334
bool TransactionIdFollowsOrEquals(TransactionId id1, TransactionId id2)
Definition: transam.c:349
bool TransactionIdPrecedesOrEquals(TransactionId id1, TransactionId id2)
Definition: transam.c:319
FullTransactionId latestCompletedXid
Definition: transam.h:233
static TransactionId ReadNextTransactionId(void)
Definition: transam.h:310
unsigned int Oid
Definition: postgres_ext.h:31
struct VariableCacheData VariableCacheData
static FullTransactionId FullTransactionIdFromU64(uint64 value)
Definition: transam.h:81
FullTransactionId nextXid
Definition: transam.h:215
Oid GetNewObjectId(void)
Definition: varsup.c:528
TransactionId xidVacLimit
Definition: transam.h:218
#define PGDLLIMPORT
Definition: c.h:1317
#define XidFromFullTransactionId(x)
Definition: transam.h:48
bool ForceTransactionIdLimitUpdate(void)
Definition: varsup.c:490
#define AssertTransactionIdInAllowableRange(xid)
Definition: transam.h:296
FullTransactionId ReadNextFullTransactionId(void)
Definition: varsup.c:261
#define FirstNormalTransactionId
Definition: transam.h:34
void AdvanceOldestClogXid(TransactionId oldest_datfrozenxid)
Definition: varsup.c:328
bool TransactionIdDidAbort(TransactionId transactionId)
Definition: transam.c:181
bool TransactionIdIsKnownCompleted(TransactionId transactionId)
Definition: transam.c:238
#define FullTransactionIdFollows(a, b)
Definition: transam.h:53
struct FullTransactionId FullTransactionId
#define FirstNormalFullTransactionId
Definition: transam.h:57
TransactionId xidStopLimit
Definition: transam.h:220
TransactionId oldestClogXid
Definition: transam.h:248
unsigned int uint32
Definition: c.h:441
TransactionId oldestCommitTsXid
Definition: transam.h:227
bool TransactionIdDidCommit(TransactionId transactionId)
Definition: transam.c:125
void TransactionIdAsyncCommitTree(TransactionId xid, int nxids, TransactionId *xids, XLogRecPtr lsn)
Definition: transam.c:272
static TransactionId NormalTransactionIdOlder(TransactionId a, TransactionId b)
Definition: transam.h:344
static TransactionId TransactionIdOlder(TransactionId a, TransactionId b)
Definition: transam.h:329
uint64 XLogRecPtr
Definition: xlogdefs.h:21
#define Assert(condition)
Definition: c.h:804
TransactionId newestCommitTsXid
Definition: transam.h:228
void TransactionIdCommitTree(TransactionId xid, int nxids, TransactionId *xids)
Definition: transam.c:260
bool TransactionStartedDuringRecovery(void)
Definition: xact.c:970
static FullTransactionId FullTransactionIdFromEpochAndXid(uint32 epoch, TransactionId xid)
Definition: transam.h:71
static TransactionId TransactionIdRetreatedBy(TransactionId xid, uint32 amount)
Definition: transam.h:317
#define NormalTransactionIdPrecedes(id1, id2)
Definition: transam.h:147
bool TransactionIdPrecedes(TransactionId id1, TransactionId id2)
Definition: transam.c:300
static FullTransactionId FullTransactionIdNewer(FullTransactionId a, FullTransactionId b)
Definition: transam.h:355
uint64 value
Definition: transam.h:67
TransactionId xidWarnLimit
Definition: transam.h:219
XLogRecPtr TransactionIdGetCommitLSN(TransactionId xid)
Definition: transam.c:402
static const unsigned __int64 epoch
Definition: gettimeofday.c:34
TransactionId xidWrapLimit
Definition: transam.h:221
#define FullTransactionIdPrecedes(a, b)
Definition: transam.h:51
#define TransactionIdIsValid(xid)
Definition: transam.h:41
#define TransactionIdIsNormal(xid)
Definition: transam.h:42
static void FullTransactionIdAdvance(FullTransactionId *dest)
Definition: transam.h:128