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