LCOV - code coverage report
Current view: top level - src/include/access - transam.h (source / functions) Hit Total Coverage
Test: PostgreSQL 14devel Lines: 37 41 90.2 %
Date: 2021-01-26 21:06:51 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     2705218 : FullTransactionIdFromEpochAndXid(uint32 epoch, TransactionId xid)
      72             : {
      73             :     FullTransactionId result;
      74             : 
      75     2705218 :     result.value = ((uint64) epoch) << 32 | xid;
      76             : 
      77     2705218 :     return result;
      78             : }
      79             : 
      80             : static inline FullTransactionId
      81    15886908 : FullTransactionIdFromU64(uint64 value)
      82             : {
      83             :     FullTransactionId result;
      84             : 
      85    15886908 :     result.value = value;
      86             : 
      87    15886908 :     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        1508 : FullTransactionIdRetreat(FullTransactionId *dest)
     104             : {
     105        1508 :     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        1508 :     if (FullTransactionIdPrecedes(*dest, FirstNormalFullTransactionId))
     113         808 :         return;
     114             : 
     115             :     /*
     116             :      * But we do need to step over XIDs that'd appear special only for 32bit
     117             :      * XIDs.
     118             :      */
     119         700 :     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      933692 : FullTransactionIdAdvance(FullTransactionId *dest)
     129             : {
     130      933692 :     dest->value++;
     131             : 
     132             :     /* see FullTransactionIdAdvance() */
     133      933692 :     if (FullTransactionIdPrecedes(*dest, FirstNormalFullTransactionId))
     134           0 :         return;
     135             : 
     136      933692 :     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.
     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             :      */
     225             :     TransactionId oldestCommitTsXid;
     226             :     TransactionId newestCommitTsXid;
     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             :      */
     241             :     uint64 xactCompletionCount;
     242             : 
     243             :     /*
     244             :      * These fields are protected by XactTruncationLock
     245             :      */
     246             :     TransactionId oldestClogXid;    /* oldest it's safe to look up in clog */
     247             : 
     248             : } VariableCacheData;
     249             : 
     250             : typedef VariableCacheData *VariableCache;
     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 */
     262             : extern PGDLLIMPORT VariableCache ShmemVariableCache;
     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);
     273             : extern bool TransactionIdPrecedes(TransactionId id1, TransactionId id2);
     274             : extern bool TransactionIdPrecedesOrEquals(TransactionId id1, TransactionId id2);
     275             : extern bool TransactionIdFollows(TransactionId id1, TransactionId id2);
     276             : extern bool TransactionIdFollowsOrEquals(TransactionId id1, TransactionId id2);
     277             : extern TransactionId TransactionIdLatest(TransactionId mainxid,
     278             :                                          int nxids, const TransactionId *xids);
     279             : extern XLogRecPtr TransactionIdGetCommitLSN(TransactionId xid);
     280             : 
     281             : /* in transam/varsup.c */
     282             : extern FullTransactionId GetNewTransactionId(bool isSubXact);
     283             : extern void AdvanceNextFullTransactionIdPastXid(TransactionId xid);
     284             : extern FullTransactionId ReadNextFullTransactionId(void);
     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
     292             : extern void AssertTransactionIdInAllowableRange(TransactionId xid);
     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
     308      115138 : ReadNewTransactionId(void)
     309             : {
     310      115138 :     return XidFromFullTransactionId(ReadNextFullTransactionId());
     311             : }
     312             : 
     313             : /* return transaction ID backed up by amount, handling wraparound correctly */
     314             : static inline TransactionId
     315     1350042 : TransactionIdRetreatedBy(TransactionId xid, uint32 amount)
     316             : {
     317     1350042 :     xid -= amount;
     318             : 
     319     1350042 :     while (xid < FirstNormalTransactionId)
     320           0 :         xid--;
     321             : 
     322     1350042 :     return xid;
     323             : }
     324             : 
     325             : /* return the older of the two IDs */
     326             : static inline TransactionId
     327     4268996 : TransactionIdOlder(TransactionId a, TransactionId b)
     328             : {
     329     4268996 :     if (!TransactionIdIsValid(a))
     330      924312 :         return b;
     331             : 
     332     3344684 :     if (!TransactionIdIsValid(b))
     333     1786934 :         return a;
     334             : 
     335     1557750 :     if (TransactionIdPrecedes(a, b))
     336      153852 :         return a;
     337     1403898 :     return b;
     338             : }
     339             : 
     340             : /* return the older of the two IDs, assuming they're both normal */
     341             : static inline TransactionId
     342             : NormalTransactionIdOlder(TransactionId a, TransactionId b)
     343             : {
     344             :     Assert(TransactionIdIsNormal(a));
     345             :     Assert(TransactionIdIsNormal(b));
     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
     353     4771986 : FullTransactionIdNewer(FullTransactionId a, FullTransactionId b)
     354             : {
     355     4771986 :     if (!FullTransactionIdIsValid(a))
     356       37284 :         return b;
     357             : 
     358     4734702 :     if (!FullTransactionIdIsValid(b))
     359       38598 :         return a;
     360             : 
     361     4696104 :     if (FullTransactionIdFollows(a, b))
     362     2795096 :         return a;
     363     1901008 :     return b;
     364             : }
     365             : 
     366             : #endif                          /* FRONTEND */
     367             : 
     368             : #endif                          /* TRANSAM_H */

Generated by: LCOV version 1.13