PostgreSQL Source Code  git master
slru.h
Go to the documentation of this file.
1 /*-------------------------------------------------------------------------
2  *
3  * slru.h
4  * Simple LRU buffering for transaction status logfiles
5  *
6  * Portions Copyright (c) 1996-2023, 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 */
49 
50 /*
51  * Shared-memory state
52  */
53 typedef struct SlruSharedData
54 {
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;
66  bool *page_dirty;
67  int64 *page_number;
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  */
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  */
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  */
99 
100  /* SLRU's index for statistics purposes (might not be unique) */
103 
105 
106 /*
107  * SlruCtlData is an unshared structure that points to the active information
108  * in shared memory.
109  */
110 typedef struct SlruCtlData
111 {
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  */
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) (int64, int64);
131 
132  /*
133  * If true, use long segment filenames formed from lower 48 bits of the
134  * segment number, e.g. pg_xact/000000001234. Otherwise, use short
135  * filenames formed from lower 16 bits of the segment number e.g.
136  * pg_xact/1234.
137  */
139 
140  /*
141  * Dir is set during SimpleLruInit and does not change thereafter. Since
142  * it's always the same, it doesn't need to be in shared memory.
143  */
144  char Dir[64];
146 
148 
149 
150 extern Size SimpleLruShmemSize(int nslots, int nlsns);
151 extern void SimpleLruInit(SlruCtl ctl, const char *name, int nslots, int nlsns,
152  LWLock *ctllock, const char *subdir, int tranche_id,
153  SyncRequestHandler sync_handler,
154  bool long_segment_names);
155 extern int SimpleLruZeroPage(SlruCtl ctl, int64 pageno);
156 extern int SimpleLruReadPage(SlruCtl ctl, int64 pageno, bool write_ok,
157  TransactionId xid);
158 extern int SimpleLruReadPage_ReadOnly(SlruCtl ctl, int64 pageno,
159  TransactionId xid);
160 extern void SimpleLruWritePage(SlruCtl ctl, int slotno);
161 extern void SimpleLruWriteAll(SlruCtl ctl, bool allow_redirtied);
162 #ifdef USE_ASSERT_CHECKING
163 extern void SlruPagePrecedesUnitTests(SlruCtl ctl, int per_page);
164 #else
165 #define SlruPagePrecedesUnitTests(ctl, per_page) do {} while (0)
166 #endif
167 extern void SimpleLruTruncate(SlruCtl ctl, int64 cutoffPage);
168 extern bool SimpleLruDoesPhysicalPageExist(SlruCtl ctl, int64 pageno);
169 
170 typedef bool (*SlruScanCallback) (SlruCtl ctl, char *filename, int64 segpage,
171  void *data);
172 extern bool SlruScanDirectory(SlruCtl ctl, SlruScanCallback callback, void *data);
173 extern void SlruDeleteSegment(SlruCtl ctl, int64 segno);
174 
175 extern int SlruSyncFileTag(SlruCtl ctl, const FileTag *ftag, char *path);
176 
177 /* SlruScanDirectory public callbacks */
178 extern bool SlruScanDirCbReportPresence(SlruCtl ctl, char *filename,
179  int64 segpage, void *data);
180 extern bool SlruScanDirCbDeleteAll(SlruCtl ctl, char *filename, int64 segpage,
181  void *data);
182 
183 #endif /* SLRU_H */
unsigned char bool
Definition: c.h:445
uint32 TransactionId
Definition: c.h:641
size_t Size
Definition: c.h:594
const void * data
static char * filename
Definition: pg_dumpall.c:121
SlruSharedData * SlruShared
Definition: slru.h:104
int SimpleLruReadPage_ReadOnly(SlruCtl ctl, int64 pageno, TransactionId xid)
Definition: slru.c:523
#define SlruPagePrecedesUnitTests(ctl, per_page)
Definition: slru.h:165
void SimpleLruWritePage(SlruCtl ctl, int slotno)
Definition: slru.c:642
bool(* SlruScanCallback)(SlruCtl ctl, char *filename, int64 segpage, void *data)
Definition: slru.h:170
void SimpleLruWriteAll(SlruCtl ctl, bool allow_redirtied)
Definition: slru.c:1184
void SimpleLruInit(SlruCtl ctl, const char *name, int nslots, int nlsns, LWLock *ctllock, const char *subdir, int tranche_id, SyncRequestHandler sync_handler, bool long_segment_names)
Definition: slru.c:214
bool SimpleLruDoesPhysicalPageExist(SlruCtl ctl, int64 pageno)
Definition: slru.c:654
void SlruDeleteSegment(SlruCtl ctl, int64 segno)
Definition: slru.c:1355
struct SlruCtlData SlruCtlData
bool SlruScanDirectory(SlruCtl ctl, SlruScanCallback callback, void *data)
Definition: slru.c:1607
bool SlruScanDirCbDeleteAll(SlruCtl ctl, char *filename, int64 segpage, void *data)
Definition: slru.c:1560
int SimpleLruReadPage(SlruCtl ctl, int64 pageno, bool write_ok, TransactionId xid)
Definition: slru.c:423
int SlruSyncFileTag(SlruCtl ctl, const FileTag *ftag, char *path)
Definition: slru.c:1647
struct SlruSharedData SlruSharedData
SlruCtlData * SlruCtl
Definition: slru.h:147
int SimpleLruZeroPage(SlruCtl ctl, int64 pageno)
Definition: slru.c:308
void SimpleLruTruncate(SlruCtl ctl, int64 cutoffPage)
Definition: slru.c:1254
SlruPageStatus
Definition: slru.h:43
@ SLRU_PAGE_VALID
Definition: slru.h:46
@ SLRU_PAGE_WRITE_IN_PROGRESS
Definition: slru.h:47
@ SLRU_PAGE_READ_IN_PROGRESS
Definition: slru.h:45
@ SLRU_PAGE_EMPTY
Definition: slru.h:44
Size SimpleLruShmemSize(int nslots, int nlsns)
Definition: slru.c:182
bool SlruScanDirCbReportPresence(SlruCtl ctl, char *filename, int64 segpage, void *data)
Definition: slru.c:1528
Definition: sync.h:51
Definition: lwlock.h:41
bool(* PagePrecedes)(int64, int64)
Definition: slru.h:130
bool long_segment_names
Definition: slru.h:138
SyncRequestHandler sync_handler
Definition: slru.h:118
SlruShared shared
Definition: slru.h:112
char Dir[64]
Definition: slru.h:144
int slru_stats_idx
Definition: slru.h:101
int64 * page_number
Definition: slru.h:67
int num_slots
Definition: slru.h:58
int * page_lru_count
Definition: slru.h:68
XLogRecPtr * group_lsn
Definition: slru.h:79
int cur_lru_count
Definition: slru.h:91
int64 latest_page_number
Definition: slru.h:98
int lsn_groups_per_page
Definition: slru.h:80
SlruPageStatus * page_status
Definition: slru.h:65
LWLock * ControlLock
Definition: slru.h:55
bool * page_dirty
Definition: slru.h:66
LWLockPadded * buffer_locks
Definition: slru.h:69
char ** page_buffer
Definition: slru.h:64
SyncRequestHandler
Definition: sync.h:36
static void callback(struct sockaddr *addr, struct sockaddr *mask, void *unused)
Definition: test_ifaddrs.c:46
const char * name
uint64 XLogRecPtr
Definition: xlogdefs.h:21