src/include/access/slru.h

   1 /*-------------------------------------------------------------------------
   2  *
   3  * slru.h
   4  *              Simple LRU buffering for transaction status logfiles
   5  *
   6  * Portions Copyright (c) 1996-2022, PostgreSQL Global Development Group
   7  * Portions Copyright (c) 1994, Regents of the University of California
   8  *
   9  * src/include/access/slru.h
  10  *
  11  *-------------------------------------------------------------------------
  12  */
  13 #ifndef SLRU_H
  14 #define SLRU_H
  15
  16 #include "access/xlogdefs.h"
  17 #include "storage/lwlock.h"
  18 #include "storage/sync.h"
  19
  20
  21 /*
  22  * Define SLRU segment size.  A page is the same BLCKSZ as is used everywhere
  23  * else in Postgres.  The segment size can be chosen somewhat arbitrarily;
  24  * we make it 32 pages by default, or 256Kb, i.e. 1M transactions for CLOG
  25  * or 64K transactions for SUBTRANS.
  26  *
  27  * Note: because TransactionIds are 32 bits and wrap around at 0xFFFFFFFF,
  28  * page numbering also wraps around at 0xFFFFFFFF/xxxx_XACTS_PER_PAGE (where
  29  * xxxx is CLOG or SUBTRANS, respectively), and segment numbering at
  30  * 0xFFFFFFFF/xxxx_XACTS_PER_PAGE/SLRU_PAGES_PER_SEGMENT.  We need
  31  * take no explicit notice of that fact in slru.c, except when comparing
  32  * segment and page numbers in SimpleLruTruncate (see PagePrecedes()).
  33  */
  34 #define SLRU_PAGES_PER_SEGMENT  32
  35
  36 /*
  37  * Page status codes.  Note that these do not include the "dirty" bit.
  38  * page_dirty can be true only in the VALID or WRITE_IN_PROGRESS states;
  39  * in the latter case it implies that the page has been re-dirtied since
  40  * the write started.
  41  */
  42 typedef enum
  43 {
  44         SLRU_PAGE_EMPTY,                        /* buffer is not in use */
  45         SLRU_PAGE_READ_IN_PROGRESS, /* page is being read in */
  46         SLRU_PAGE_VALID,                        /* page is valid and not being written */
  47         SLRU_PAGE_WRITE_IN_PROGRESS /* page is being written out */
  48 } SlruPageStatus;
  49
  50 /*
  51  * Shared-memory state
  52  */
  53 typedef struct SlruSharedData
  54 {
  55         LWLock     *ControlLock;
  56
  57         /* Number of buffers managed by this SLRU structure */
  58         int                     num_slots;
  59
  60         /*
  61          * Arrays holding info for each buffer slot.  Page number is undefined
  62          * when status is EMPTY, as is page_lru_count.
  63          */
  64         char      **page_buffer;
  65         SlruPageStatus *page_status;
  66         bool       *page_dirty;
  67         int                *page_number;
  68         int                *page_lru_count;
  69         LWLockPadded *buffer_locks;
  70
  71         /*
  72          * Optional array of WAL flush LSNs associated with entries in the SLRU
  73          * pages.  If not zero/NULL, we must flush WAL before writing pages (true
  74          * for pg_xact, false for multixact, pg_subtrans, pg_notify).  group_lsn[]
  75          * has lsn_groups_per_page entries per buffer slot, each containing the
  76          * highest LSN known for a contiguous group of SLRU entries on that slot's
  77          * page.
  78          */
  79         XLogRecPtr *group_lsn;
  80         int                     lsn_groups_per_page;
  81
  82         /*----------
  83          * We mark a page "most recently used" by setting
  84          *              page_lru_count[slotno] = ++cur_lru_count;
  85          * The oldest page is therefore the one with the highest value of
  86          *              cur_lru_count - page_lru_count[slotno]
  87          * The counts will eventually wrap around, but this calculation still
  88          * works as long as no page's age exceeds INT_MAX counts.
  89          *----------
  90          */
  91         int                     cur_lru_count;
  92
  93         /*
  94          * latest_page_number is the page number of the current end of the log;
  95          * this is not critical data, since we use it only to avoid swapping out
  96          * the latest page.
  97          */
  98         int                     latest_page_number;
  99
 100         /* SLRU's index for statistics purposes (might not be unique) */
 101         int                     slru_stats_idx;
 102 } SlruSharedData;
 103
 104 typedef SlruSharedData *SlruShared;
 105
 106 /*
 107  * SlruCtlData is an unshared structure that points to the active information
 108  * in shared memory.
 109  */
 110 typedef struct SlruCtlData
 111 {
 112         SlruShared      shared;
 113
 114         /*
 115          * Which sync handler function to use when handing sync requests over to
 116          * the checkpointer.  SYNC_HANDLER_NONE to disable fsync (eg pg_notify).
 117          */
 118         SyncRequestHandler sync_handler;
 119
 120         /*
 121          * Decide whether a page is "older" for truncation and as a hint for
 122          * evicting pages in LRU order.  Return true if every entry of the first
 123          * argument is older than every entry of the second argument.  Note that
 124          * !PagePrecedes(a,b) && !PagePrecedes(b,a) need not imply a==b; it also
 125          * arises when some entries are older and some are not.  For SLRUs using
 126          * SimpleLruTruncate(), this must use modular arithmetic.  (For others,
 127          * the behavior of this callback has no functional implications.)  Use
 128          * SlruPagePrecedesUnitTests() in SLRUs meeting its criteria.
 129          */
 130         bool            (*PagePrecedes) (int, int);
 131
 132         /*
 133          * Dir is set during SimpleLruInit and does not change thereafter. Since
 134          * it's always the same, it doesn't need to be in shared memory.
 135          */
 136         char            Dir[64];
 137 } SlruCtlData;
 138
 139 typedef SlruCtlData *SlruCtl;
 140
 141
 142 extern Size SimpleLruShmemSize(int nslots, int nlsns);
 143 extern void SimpleLruInit(SlruCtl ctl, const char *name, int nslots, int nlsns,
 144                                                   LWLock *ctllock, const char *subdir, int tranche_id,
 145                                                   SyncRequestHandler sync_handler);
 146 extern int      SimpleLruZeroPage(SlruCtl ctl, int pageno);
 147 extern int      SimpleLruReadPage(SlruCtl ctl, int pageno, bool write_ok,
 148                                                           TransactionId xid);
 149 extern int      SimpleLruReadPage_ReadOnly(SlruCtl ctl, int pageno,
 150                                                                            TransactionId xid);
 151 extern void SimpleLruWritePage(SlruCtl ctl, int slotno);
 152 extern void SimpleLruWriteAll(SlruCtl ctl, bool allow_redirtied);
 153 #ifdef USE_ASSERT_CHECKING
 154 extern void SlruPagePrecedesUnitTests(SlruCtl ctl, int per_page);
 155 #else
 156 #define SlruPagePrecedesUnitTests(ctl, per_page) do {} while (0)
 157 #endif
 158 extern void SimpleLruTruncate(SlruCtl ctl, int cutoffPage);
 159 extern bool SimpleLruDoesPhysicalPageExist(SlruCtl ctl, int pageno);
 160
 161 typedef bool (*SlruScanCallback) (SlruCtl ctl, char *filename, int segpage,
 162                                                                   void *data);
 163 extern bool SlruScanDirectory(SlruCtl ctl, SlruScanCallback callback, void *data);
 164 extern void SlruDeleteSegment(SlruCtl ctl, int segno);
 165
 166 extern int      SlruSyncFileTag(SlruCtl ctl, const FileTag *ftag, char *path);
 167
 168 /* SlruScanDirectory public callbacks */
 169 extern bool SlruScanDirCbReportPresence(SlruCtl ctl, char *filename,
 170                                                                                 int segpage, void *data);
 171 extern bool SlruScanDirCbDeleteAll(SlruCtl ctl, char *filename, int segpage,
 172                                                                    void *data);
 173
 174 #endif                                                  /* SLRU_H */