LCOV - code coverage report
Current view: top level - src/include/access - transam.h (source / functions) Hit Total Coverage
Test: PostgreSQL 15devel Lines: 37 41 90.2 %
Date: 2021-12-05 01:09:12 Functions: 8 8 100.0 %
Legend: Lines: hit not hit

          Line data    Source code
       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;
      68             : } FullTransactionId;
      69             : 
      70             : static inline FullTransactionId
      71     3689784 : FullTransactionIdFromEpochAndXid(uint32 epoch, TransactionId xid)
      72             : {
      73             :     FullTransactionId result;
      74             : 
      75     3689784 :     result.value = ((uint64) epoch) << 32 | xid;
      76             : 
      77     3689784 :     return result;
      78             : }
      79             : 
      80             : static inline FullTransactionId
      81    18441636 : FullTransactionIdFromU64(uint64 value)
      82             : {
      83             :     FullTransactionId result;
      84             : 
      85    18441636 :     result.value = value;
      86             : 
      87    18441636 :     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        1808 : FullTransactionIdRetreat(FullTransactionId *dest)
     104             : {
     105        1808 :     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        1808 :     if (FullTransactionIdPrecedes(*dest, FirstNormalFullTransactionId))
     113         964 :         return;
     114             : 
     115             :     /*
     116             :      * But we do need to step over XIDs that'd appear special only for 32bit
     117             :      * XIDs.
     118             :      */
     119         844 :     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     1361180 : FullTransactionIdAdvance(FullTransactionId *dest)
     129             : {
     130     1361180 :     dest->value++;
     131             : 
     132             :     /* see FullTransactionIdAdvance() */
     133     1361180 :     if (FullTransactionIdPrecedes(*dest, FirstNormalFullTransactionId))
     134           0 :         return;
     135             : 
     136     1361180 :     while (XidFromFullTransactionId(*dest) < FirstNormalTransactionId)
     137           0 :         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             :      */
     232             :     TransactionId oldestCommitTsXid;
     233             :     TransactionId newestCommitTsXid;
     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             :      */
     248             :     uint64      xactCompletionCount;
     249             : 
     250             :     /*
     251             :      * These fields are protected by XactTruncationLock
     252             :      */
     253             :     TransactionId oldestClogXid;    /* oldest it's safe to look up in clog */
     254             : 
     255             : } VariableCacheData;
     256             : 
     257             : typedef VariableCacheData *VariableCache;
     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 */
     269             : extern PGDLLIMPORT VariableCache ShmemVariableCache;
     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);
     280             : extern bool TransactionIdPrecedes(TransactionId id1, TransactionId id2);
     281             : extern bool TransactionIdPrecedesOrEquals(TransactionId id1, TransactionId id2);
     282             : extern bool TransactionIdFollows(TransactionId id1, TransactionId id2);
     283             : extern bool TransactionIdFollowsOrEquals(TransactionId id1, TransactionId id2);
     284             : extern TransactionId TransactionIdLatest(TransactionId mainxid,
     285             :                                          int nxids, const TransactionId *xids);
     286             : extern XLogRecPtr TransactionIdGetCommitLSN(TransactionId xid);
     287             : 
     288             : /* in transam/varsup.c */
     289             : extern FullTransactionId GetNewTransactionId(bool isSubXact);
     290             : extern void AdvanceNextFullTransactionIdPastXid(TransactionId xid);
     291             : extern FullTransactionId ReadNextFullTransactionId(void);
     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
     300             : extern void AssertTransactionIdInAllowableRange(TransactionId xid);
     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
     316      192208 : ReadNextTransactionId(void)
     317             : {
     318      192208 :     return XidFromFullTransactionId(ReadNextFullTransactionId());
     319             : }
     320             : 
     321             : /* return transaction ID backed up by amount, handling wraparound correctly */
     322             : static inline TransactionId
     323     2231666 : TransactionIdRetreatedBy(TransactionId xid, uint32 amount)
     324             : {
     325     2231666 :     xid -= amount;
     326             : 
     327     2231666 :     while (xid < FirstNormalTransactionId)
     328           0 :         xid--;
     329             : 
     330     2231666 :     return xid;
     331             : }
     332             : 
     333             : /* return the older of the two IDs */
     334             : static inline TransactionId
     335     6548920 : TransactionIdOlder(TransactionId a, TransactionId b)
     336             : {
     337     6548920 :     if (!TransactionIdIsValid(a))
     338     1241844 :         return b;
     339             : 
     340     5307076 :     if (!TransactionIdIsValid(b))
     341     2830526 :         return a;
     342             : 
     343     2476550 :     if (TransactionIdPrecedes(a, b))
     344      204536 :         return a;
     345     2272014 :     return b;
     346             : }
     347             : 
     348             : /* return the older of the two IDs, assuming they're both normal */
     349             : static inline TransactionId
     350             : NormalTransactionIdOlder(TransactionId a, TransactionId b)
     351             : {
     352             :     Assert(TransactionIdIsNormal(a));
     353             :     Assert(TransactionIdIsNormal(b));
     354             :     if (NormalTransactionIdPrecedes(a, b))
     355             :         return a;
     356             :     return b;
     357             : }
     358             : 
     359             : /* return the newer of the two IDs */
     360             : static inline FullTransactionId
     361     6821544 : FullTransactionIdNewer(FullTransactionId a, FullTransactionId b)
     362             : {
     363     6821544 :     if (!FullTransactionIdIsValid(a))
     364       47364 :         return b;
     365             : 
     366     6774180 :     if (!FullTransactionIdIsValid(b))
     367       48966 :         return a;
     368             : 
     369     6725214 :     if (FullTransactionIdFollows(a, b))
     370     4132802 :         return a;
     371     2592412 :     return b;
     372             : }
     373             : 
     374             : #endif                          /* FRONTEND */
     375             : 
     376             : #endif                          /* TRANSAM_H */

Generated by: LCOV version 1.14