LCOV - code coverage report
Current view: top level - src/include/access - transam.h (source / functions) Hit Total Coverage
Test: PostgreSQL 17devel Lines: 33 36 91.7 %
Date: 2024-02-22 00:11:39 Functions: 7 7 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-2024, 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     2403514 : FullTransactionIdFromEpochAndXid(uint32 epoch, TransactionId xid)
      72             : {
      73             :     FullTransactionId result;
      74             : 
      75     2403514 :     result.value = ((uint64) epoch) << 32 | xid;
      76             : 
      77     2403514 :     return result;
      78             : }
      79             : 
      80             : static inline FullTransactionId
      81    21424330 : FullTransactionIdFromU64(uint64 value)
      82             : {
      83             :     FullTransactionId result;
      84             : 
      85    21424330 :     result.value = value;
      86             : 
      87    21424330 :     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        1348 : FullTransactionIdRetreat(FullTransactionId *dest)
     104             : {
     105        1348 :     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        1348 :     if (FullTransactionIdPrecedes(*dest, FirstNormalFullTransactionId))
     113         132 :         return;
     114             : 
     115             :     /*
     116             :      * But we do need to step over XIDs that'd appear special only for 32bit
     117             :      * XIDs.
     118             :      */
     119        1216 :     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      746232 : FullTransactionIdAdvance(FullTransactionId *dest)
     129             : {
     130      746232 :     dest->value++;
     131             : 
     132             :     /* see FullTransactionIdAdvance() */
     133      746232 :     if (FullTransactionIdPrecedes(*dest, FirstNormalFullTransactionId))
     134           0 :         return;
     135             : 
     136      746232 :     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             :  * TransamVariables 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 TransamVariablesData
     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             : } TransamVariablesData;
     256             : 
     257             : 
     258             : /* ----------------
     259             :  *      extern declarations
     260             :  * ----------------
     261             :  */
     262             : 
     263             : /* in transam/xact.c */
     264             : extern bool TransactionStartedDuringRecovery(void);
     265             : 
     266             : /* in transam/varsup.c */
     267             : extern PGDLLIMPORT TransamVariablesData *TransamVariables;
     268             : 
     269             : /*
     270             :  * prototypes for functions in transam/transam.c
     271             :  */
     272             : extern bool TransactionIdDidCommit(TransactionId transactionId);
     273             : extern bool TransactionIdDidAbort(TransactionId transactionId);
     274             : extern void TransactionIdCommitTree(TransactionId xid, int nxids, TransactionId *xids);
     275             : extern void TransactionIdAsyncCommitTree(TransactionId xid, int nxids, TransactionId *xids, XLogRecPtr lsn);
     276             : extern void TransactionIdAbortTree(TransactionId xid, int nxids, TransactionId *xids);
     277             : extern bool TransactionIdPrecedes(TransactionId id1, TransactionId id2);
     278             : extern bool TransactionIdPrecedesOrEquals(TransactionId id1, TransactionId id2);
     279             : extern bool TransactionIdFollows(TransactionId id1, TransactionId id2);
     280             : extern bool TransactionIdFollowsOrEquals(TransactionId id1, TransactionId id2);
     281             : extern TransactionId TransactionIdLatest(TransactionId mainxid,
     282             :                                          int nxids, const TransactionId *xids);
     283             : extern XLogRecPtr TransactionIdGetCommitLSN(TransactionId xid);
     284             : 
     285             : /* in transam/varsup.c */
     286             : extern Size VarsupShmemSize(void);
     287             : extern void VarsupShmemInit(void);
     288             : extern FullTransactionId GetNewTransactionId(bool isSubXact);
     289             : extern void AdvanceNextFullTransactionIdPastXid(TransactionId xid);
     290             : extern FullTransactionId ReadNextFullTransactionId(void);
     291             : extern void SetTransactionIdLimit(TransactionId oldest_datfrozenxid,
     292             :                                   Oid oldest_datoid);
     293             : extern void AdvanceOldestClogXid(TransactionId oldest_datfrozenxid);
     294             : extern bool ForceTransactionIdLimitUpdate(void);
     295             : extern Oid  GetNewObjectId(void);
     296             : extern void StopGeneratingPinnedObjectIds(void);
     297             : 
     298             : #ifdef USE_ASSERT_CHECKING
     299             : extern void AssertTransactionIdInAllowableRange(TransactionId xid);
     300             : #else
     301             : #define AssertTransactionIdInAllowableRange(xid) ((void)true)
     302             : #endif
     303             : 
     304             : /*
     305             :  * Some frontend programs include this header.  For compilers that emit static
     306             :  * inline functions even when they're unused, that leads to unsatisfied
     307             :  * external references; hence hide them with #ifndef FRONTEND.
     308             :  */
     309             : #ifndef FRONTEND
     310             : 
     311             : /*
     312             :  * For callers that just need the XID part of the next transaction ID.
     313             :  */
     314             : static inline TransactionId
     315       38710 : ReadNextTransactionId(void)
     316             : {
     317       38710 :     return XidFromFullTransactionId(ReadNextFullTransactionId());
     318             : }
     319             : 
     320             : /* return transaction ID backed up by amount, handling wraparound correctly */
     321             : static inline TransactionId
     322             : TransactionIdRetreatedBy(TransactionId xid, uint32 amount)
     323             : {
     324             :     xid -= amount;
     325             : 
     326             :     while (xid < FirstNormalTransactionId)
     327             :         xid--;
     328             : 
     329             :     return xid;
     330             : }
     331             : 
     332             : /* return the older of the two IDs */
     333             : static inline TransactionId
     334     4106772 : TransactionIdOlder(TransactionId a, TransactionId b)
     335             : {
     336     4106772 :     if (!TransactionIdIsValid(a))
     337     1002078 :         return b;
     338             : 
     339     3104694 :     if (!TransactionIdIsValid(b))
     340     1473138 :         return a;
     341             : 
     342     1631556 :     if (TransactionIdPrecedes(a, b))
     343      374332 :         return a;
     344     1257224 :     return b;
     345             : }
     346             : 
     347             : /* return the older of the two IDs, assuming they're both normal */
     348             : static inline TransactionId
     349             : NormalTransactionIdOlder(TransactionId a, TransactionId b)
     350             : {
     351             :     Assert(TransactionIdIsNormal(a));
     352             :     Assert(TransactionIdIsNormal(b));
     353             :     if (NormalTransactionIdPrecedes(a, b))
     354             :         return a;
     355             :     return b;
     356             : }
     357             : 
     358             : /* return the newer of the two IDs */
     359             : static inline FullTransactionId
     360     4051350 : FullTransactionIdNewer(FullTransactionId a, FullTransactionId b)
     361             : {
     362     4051350 :     if (!FullTransactionIdIsValid(a))
     363       74772 :         return b;
     364             : 
     365     3976578 :     if (!FullTransactionIdIsValid(b))
     366       77076 :         return a;
     367             : 
     368     3899502 :     if (FullTransactionIdFollows(a, b))
     369     2182528 :         return a;
     370     1716974 :     return b;
     371             : }
     372             : 
     373             : #endif                          /* FRONTEND */
     374             : 
     375             : #endif                          /* TRANSAM_H */

Generated by: LCOV version 1.14