src/include/utils/tqual.h

   1 /*-------------------------------------------------------------------------
   2  *
   3  * tqual.h
   4  *        POSTGRES "time qualification" definitions, ie, tuple visibility rules.
   5  *
   6  *        Should be moved/renamed...    - vadim 07/28/98
   7  *
   8  * Portions Copyright (c) 1996-2007, PostgreSQL Global Development Group
   9  * Portions Copyright (c) 1994, Regents of the University of California
  10  *
  11  * $PostgreSQL: pgsql/src/include/utils/tqual.h,v 1.69 2007/11/15 21:14:45 momjian Exp $
  12  *
  13  *-------------------------------------------------------------------------
  14  */
  15 #ifndef TQUAL_H
  16 #define TQUAL_H
  17
  18 #include "access/htup.h"
  19 #include "storage/buf.h"
  20
  21
  22 /*
  23  * We use SnapshotData structures to represent both "regular" (MVCC)
  24  * snapshots and "special" snapshots that have non-MVCC semantics.
  25  * The specific semantics of a snapshot are encoded by the "satisfies"
  26  * function.
  27  */
  28 typedef struct SnapshotData *Snapshot;
  29
  30 typedef bool (*SnapshotSatisfiesFunc) (HeapTupleHeader tuple,
  31                                                                                    Snapshot snapshot, Buffer buffer);
  32
  33 typedef struct SnapshotData
  34 {
  35         SnapshotSatisfiesFunc satisfies;        /* tuple test function */
  36
  37         /*
  38          * The remaining fields are used only for MVCC snapshots, and are normally
  39          * just zeroes in special snapshots.  (But xmin and xmax are used
  40          * specially by HeapTupleSatisfiesDirty.)
  41          *
  42          * An MVCC snapshot can never see the effects of XIDs >= xmax. It can see
  43          * the effects of all older XIDs except those listed in the snapshot.
  44          * xmin is stored as an optimization to avoid needing to search the XID
  45          * arrays for most tuples.
  46          */
  47         TransactionId xmin;                     /* all XID < xmin are visible to me */
  48         TransactionId xmax;                     /* all XID >= xmax are invisible to me */
  49         uint32          xcnt;                   /* # of xact ids in xip[] */
  50         TransactionId *xip;                     /* array of xact IDs in progress */
  51         /* note: all ids in xip[] satisfy xmin <= xip[i] < xmax */
  52         int32           subxcnt;                /* # of xact ids in subxip[], -1 if overflow */
  53         TransactionId *subxip;          /* array of subxact IDs in progress */
  54
  55         /*
  56          * note: all ids in subxip[] are >= xmin, but we don't bother filtering
  57          * out any that are >= xmax
  58          */
  59         CommandId       curcid;                 /* in my xact, CID < curcid are visible */
  60 } SnapshotData;
  61
  62 #define InvalidSnapshot         ((Snapshot) NULL)
  63
  64 /* Static variables representing various special snapshot semantics */
  65 extern PGDLLIMPORT SnapshotData SnapshotNowData;
  66 extern PGDLLIMPORT SnapshotData SnapshotSelfData;
  67 extern PGDLLIMPORT SnapshotData SnapshotAnyData;
  68 extern PGDLLIMPORT SnapshotData SnapshotToastData;
  69
  70 #define SnapshotNow                     (&SnapshotNowData)
  71 #define SnapshotSelf            (&SnapshotSelfData)
  72 #define SnapshotAny                     (&SnapshotAnyData)
  73 #define SnapshotToast           (&SnapshotToastData)
  74
  75 /*
  76  * We don't provide a static SnapshotDirty variable because it would be
  77  * non-reentrant.  Instead, users of that snapshot type should declare a
  78  * local variable of type SnapshotData, and initialize it with this macro.
  79  */
  80 #define InitDirtySnapshot(snapshotdata)  \
  81         ((snapshotdata).satisfies = HeapTupleSatisfiesDirty)
  82
  83 /* This macro encodes the knowledge of which snapshots are MVCC-safe */
  84 #define IsMVCCSnapshot(snapshot)  \
  85         ((snapshot)->satisfies == HeapTupleSatisfiesMVCC)
  86
  87
  88 extern PGDLLIMPORT Snapshot SerializableSnapshot;
  89 extern PGDLLIMPORT Snapshot LatestSnapshot;
  90 extern PGDLLIMPORT Snapshot ActiveSnapshot;
  91
  92 extern TransactionId TransactionXmin;
  93 extern TransactionId RecentXmin;
  94 extern TransactionId RecentGlobalXmin;
  95
  96 /*
  97  * HeapTupleSatisfiesVisibility
  98  *              True iff heap tuple satisfies a time qual.
  99  *
 100  * Notes:
 101  *      Assumes heap tuple is valid.
 102  *      Beware of multiple evaluations of snapshot argument.
 103  *      Hint bits in the HeapTuple's t_infomask may be updated as a side effect;
 104  *      if so, the indicated buffer is marked dirty.
 105  */
 106 #define HeapTupleSatisfiesVisibility(tuple, snapshot, buffer) \
 107         ((*(snapshot)->satisfies) ((tuple)->t_data, snapshot, buffer))
 108
 109 /* Result codes for HeapTupleSatisfiesUpdate */
 110 typedef enum
 111 {
 112         HeapTupleMayBeUpdated,
 113         HeapTupleInvisible,
 114         HeapTupleSelfUpdated,
 115         HeapTupleUpdated,
 116         HeapTupleBeingUpdated
 117 } HTSU_Result;
 118
 119 /* Result codes for HeapTupleSatisfiesVacuum */
 120 typedef enum
 121 {
 122         HEAPTUPLE_DEAD,                         /* tuple is dead and deletable */
 123         HEAPTUPLE_LIVE,                         /* tuple is live (committed, no deleter) */
 124         HEAPTUPLE_RECENTLY_DEAD,        /* tuple is dead, but not deletable yet */
 125         HEAPTUPLE_INSERT_IN_PROGRESS,           /* inserting xact is still in progress */
 126         HEAPTUPLE_DELETE_IN_PROGRESS    /* deleting xact is still in progress */
 127 } HTSV_Result;
 128
 129 /* These are the "satisfies" test routines for the various snapshot types */
 130 extern bool HeapTupleSatisfiesMVCC(HeapTupleHeader tuple,
 131                                            Snapshot snapshot, Buffer buffer);
 132 extern bool HeapTupleSatisfiesNow(HeapTupleHeader tuple,
 133                                           Snapshot snapshot, Buffer buffer);
 134 extern bool HeapTupleSatisfiesSelf(HeapTupleHeader tuple,
 135                                            Snapshot snapshot, Buffer buffer);
 136 extern bool HeapTupleSatisfiesAny(HeapTupleHeader tuple,
 137                                           Snapshot snapshot, Buffer buffer);
 138 extern bool HeapTupleSatisfiesToast(HeapTupleHeader tuple,
 139                                                 Snapshot snapshot, Buffer buffer);
 140 extern bool HeapTupleSatisfiesDirty(HeapTupleHeader tuple,
 141                                                 Snapshot snapshot, Buffer buffer);
 142
 143 /* Special "satisfies" routines with different APIs */
 144 extern HTSU_Result HeapTupleSatisfiesUpdate(HeapTupleHeader tuple,
 145                                                  CommandId curcid, Buffer buffer);
 146 extern HTSV_Result HeapTupleSatisfiesVacuum(HeapTupleHeader tuple,
 147                                                  TransactionId OldestXmin, Buffer buffer);
 148
 149 extern void HeapTupleSetHintBits(HeapTupleHeader tuple, Buffer buffer,
 150                                          uint16 infomask, TransactionId xid);
 151
 152 extern Snapshot GetTransactionSnapshot(void);
 153 extern Snapshot GetLatestSnapshot(void);
 154 extern Snapshot CopySnapshot(Snapshot snapshot);
 155 extern void FreeSnapshot(Snapshot snapshot);
 156 extern void FreeXactSnapshot(void);
 157
 158 /* in procarray.c; declared here to avoid including tqual.h in procarray.h: */
 159 extern Snapshot GetSnapshotData(Snapshot snapshot, bool serializable);
 160
 161 #endif   /* TQUAL_H */