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 
58 /*
59  * A 64 bit value that contains an epoch and a TransactionId. This is
60  * wrapped in a struct to prevent implicit conversion to/from TransactionId.
61  * Not all values represent valid normal XIDs.
62  */
63 typedef struct FullTransactionId
64 {
65  uint64 value;
67 
68 static inline FullTransactionId
70 {
71  FullTransactionId result;
72 
73  result.value = ((uint64) epoch) << 32 | xid;
74 
75  return result;
76 }
77 
78 static inline FullTransactionId
80 {
81  FullTransactionId result;
82 
83  result.value = value;
84 
85  return result;
86 }
87 
88 /* advance a transaction ID variable, handling wraparound correctly */
89 #define TransactionIdAdvance(dest) \
90  do { \
91  (dest)++; \
92  if ((dest) < FirstNormalTransactionId) \
93  (dest) = FirstNormalTransactionId; \
94  } while(0)
95 
96 /* advance a FullTransactionId variable, stepping over special XIDs */
97 static inline void
99 {
100  dest->value++;
102  dest->value++;
103 }
104 
105 /* back up a transaction ID variable, handling wraparound correctly */
106 #define TransactionIdRetreat(dest) \
107  do { \
108  (dest)--; \
109  } while ((dest) < FirstNormalTransactionId)
110 
111 /* compare two XIDs already known to be normal; this is a macro for speed */
112 #define NormalTransactionIdPrecedes(id1, id2) \
113  (AssertMacro(TransactionIdIsNormal(id1) && TransactionIdIsNormal(id2)), \
114  (int32) ((id1) - (id2)) < 0)
115 
116 /* compare two XIDs already known to be normal; this is a macro for speed */
117 #define NormalTransactionIdFollows(id1, id2) \
118  (AssertMacro(TransactionIdIsNormal(id1) && TransactionIdIsNormal(id2)), \
119  (int32) ((id1) - (id2)) > 0)
120 
121 /* ----------
122  * Object ID (OID) zero is InvalidOid.
123  *
124  * OIDs 1-9999 are reserved for manual assignment (see .dat files in
125  * src/include/catalog/). Of these, 8000-9999 are reserved for
126  * development purposes (such as in-progress patches and forks);
127  * they should not appear in released versions.
128  *
129  * OIDs 10000-11999 are reserved for assignment by genbki.pl, for use
130  * when the .dat files in src/include/catalog/ do not specify an OID
131  * for a catalog entry that requires one.
132  *
133  * OIDS 12000-16383 are reserved for assignment during initdb
134  * using the OID generator. (We start the generator at 12000.)
135  *
136  * OIDs beginning at 16384 are assigned from the OID generator
137  * during normal multiuser operation. (We force the generator up to
138  * 16384 as soon as we are in normal operation.)
139  *
140  * The choices of 8000, 10000 and 12000 are completely arbitrary, and can be
141  * moved if we run low on OIDs in any category. Changing the macros below,
142  * and updating relevant documentation (see bki.sgml and RELEASE_CHANGES),
143  * should be sufficient to do this. Moving the 16384 boundary between
144  * initdb-assigned OIDs and user-defined objects would be substantially
145  * more painful, however, since some user-defined OIDs will appear in
146  * on-disk data; such a change would probably break pg_upgrade.
147  *
148  * NOTE: if the OID generator wraps around, we skip over OIDs 0-16383
149  * and resume with 16384. This minimizes the odds of OID conflict, by not
150  * reassigning OIDs that might have been assigned during initdb.
151  * ----------
152  */
153 #define FirstGenbkiObjectId 10000
154 #define FirstBootstrapObjectId 12000
155 #define FirstNormalObjectId 16384
156 
157 /*
158  * VariableCache is a data structure in shared memory that is used to track
159  * OID and XID assignment state. For largely historical reasons, there is
160  * just one struct with different fields that are protected by different
161  * LWLocks.
162  *
163  * Note: xidWrapLimit and oldestXidDB are not "active" values, but are
164  * used just to generate useful messages when xidWarnLimit or xidStopLimit
165  * are exceeded.
166  */
167 typedef struct VariableCacheData
168 {
169  /*
170  * These fields are protected by OidGenLock.
171  */
172  Oid nextOid; /* next OID to assign */
173  uint32 oidCount; /* OIDs available before must do XLOG work */
174 
175  /*
176  * These fields are protected by XidGenLock.
177  */
178  FullTransactionId nextFullXid; /* next full XID to assign */
179 
180  TransactionId oldestXid; /* cluster-wide minimum datfrozenxid */
181  TransactionId xidVacLimit; /* start forcing autovacuums here */
182  TransactionId xidWarnLimit; /* start complaining here */
183  TransactionId xidStopLimit; /* refuse to advance nextFullXid beyond here */
184  TransactionId xidWrapLimit; /* where the world ends */
185  Oid oldestXidDB; /* database with minimum datfrozenxid */
186 
187  /*
188  * These fields are protected by CommitTsLock
189  */
192 
193  /*
194  * These fields are protected by ProcArrayLock.
195  */
196  TransactionId latestCompletedXid; /* newest XID that has committed or
197  * aborted */
198 
199  /*
200  * These fields are protected by XactTruncationLock
201  */
202  TransactionId oldestClogXid; /* oldest it's safe to look up in clog */
203 
205 
207 
208 
209 /* ----------------
210  * extern declarations
211  * ----------------
212  */
213 
214 /* in transam/xact.c */
215 extern bool TransactionStartedDuringRecovery(void);
216 
217 /* in transam/varsup.c */
219 
220 /*
221  * prototypes for functions in transam/transam.c
222  */
223 extern bool TransactionIdDidCommit(TransactionId transactionId);
224 extern bool TransactionIdDidAbort(TransactionId transactionId);
225 extern bool TransactionIdIsKnownCompleted(TransactionId transactionId);
226 extern void TransactionIdCommitTree(TransactionId xid, int nxids, TransactionId *xids);
227 extern void TransactionIdAsyncCommitTree(TransactionId xid, int nxids, TransactionId *xids, XLogRecPtr lsn);
228 extern void TransactionIdAbortTree(TransactionId xid, int nxids, TransactionId *xids);
231 extern bool TransactionIdFollows(TransactionId id1, TransactionId id2);
234  int nxids, const TransactionId *xids);
236 
237 /* in transam/varsup.c */
238 extern FullTransactionId GetNewTransactionId(bool isSubXact);
241 extern void SetTransactionIdLimit(TransactionId oldest_datfrozenxid,
242  Oid oldest_datoid);
243 extern void AdvanceOldestClogXid(TransactionId oldest_datfrozenxid);
244 extern bool ForceTransactionIdLimitUpdate(void);
245 extern Oid GetNewObjectId(void);
246 
247 /*
248  * Some frontend programs include this header. For compilers that emit static
249  * inline functions even when they're unused, that leads to unsatisfied
250  * external references; hence hide them with #ifndef FRONTEND.
251  */
252 #ifndef FRONTEND
253 
254 /*
255  * For callers that just need the XID part of the next transaction ID.
256  */
257 static inline TransactionId
259 {
261 }
262 
263 #endif /* FRONTEND */
264 
265 #endif /* TRANSAM_H */
void AdvanceNextFullTransactionIdPastXid(TransactionId xid)
Definition: varsup.c:262
VariableCacheData * VariableCache
Definition: transam.h:206
TransactionId TransactionIdLatest(TransactionId mainxid, int nxids, const TransactionId *xids)
Definition: transam.c:365
void SetTransactionIdLimit(TransactionId oldest_datfrozenxid, Oid oldest_datoid)
Definition: varsup.c:330
void TransactionIdAbortTree(TransactionId xid, int nxids, TransactionId *xids)
Definition: transam.c:290
uint32 TransactionId
Definition: c.h:513
uint32 oidCount
Definition: transam.h:173
FullTransactionId GetNewTransactionId(bool isSubXact)
Definition: varsup.c:49
PGDLLIMPORT VariableCache ShmemVariableCache
Definition: varsup.c:34
TransactionId oldestXid
Definition: transam.h:180
bool TransactionIdFollows(TransactionId id1, TransactionId id2)
Definition: transam.c:334
bool TransactionIdFollowsOrEquals(TransactionId id1, TransactionId id2)
Definition: transam.c:349
FullTransactionId nextFullXid
Definition: transam.h:178
bool TransactionIdPrecedesOrEquals(TransactionId id1, TransactionId id2)
Definition: transam.c:319
unsigned int Oid
Definition: postgres_ext.h:31
struct VariableCacheData VariableCacheData
static FullTransactionId FullTransactionIdFromU64(uint64 value)
Definition: transam.h:79
Oid GetNewObjectId(void)
Definition: varsup.c:509
TransactionId xidVacLimit
Definition: transam.h:181
#define PGDLLIMPORT
Definition: c.h:1280
#define XidFromFullTransactionId(x)
Definition: transam.h:48
bool ForceTransactionIdLimitUpdate(void)
Definition: varsup.c:471
FullTransactionId ReadNextFullTransactionId(void)
Definition: varsup.c:246
#define FirstNormalTransactionId
Definition: transam.h:34
void AdvanceOldestClogXid(TransactionId oldest_datfrozenxid)
Definition: varsup.c:313
bool TransactionIdDidAbort(TransactionId transactionId)
Definition: transam.c:181
bool TransactionIdIsKnownCompleted(TransactionId transactionId)
Definition: transam.c:238
struct FullTransactionId FullTransactionId
TransactionId xidStopLimit
Definition: transam.h:183
TransactionId oldestClogXid
Definition: transam.h:202
unsigned int uint32
Definition: c.h:367
TransactionId oldestCommitTsXid
Definition: transam.h:190
bool TransactionIdDidCommit(TransactionId transactionId)
Definition: transam.c:125
void TransactionIdAsyncCommitTree(TransactionId xid, int nxids, TransactionId *xids, XLogRecPtr lsn)
Definition: transam.c:272
uint64 XLogRecPtr
Definition: xlogdefs.h:21
TransactionId newestCommitTsXid
Definition: transam.h:191
void TransactionIdCommitTree(TransactionId xid, int nxids, TransactionId *xids)
Definition: transam.c:260
bool TransactionStartedDuringRecovery(void)
Definition: xact.c:955
static FullTransactionId FullTransactionIdFromEpochAndXid(uint32 epoch, TransactionId xid)
Definition: transam.h:69
bool TransactionIdPrecedes(TransactionId id1, TransactionId id2)
Definition: transam.c:300
static TransactionId ReadNewTransactionId(void)
Definition: transam.h:258
uint64 value
Definition: transam.h:65
TransactionId xidWarnLimit
Definition: transam.h:182
XLogRecPtr TransactionIdGetCommitLSN(TransactionId xid)
Definition: transam.c:402
static const unsigned __int64 epoch
Definition: gettimeofday.c:34
TransactionId xidWrapLimit
Definition: transam.h:184
static void FullTransactionIdAdvance(FullTransactionId *dest)
Definition: transam.h:98
TransactionId latestCompletedXid
Definition: transam.h:196