1 | /* |
2 | ** 2008 August 05 |
3 | ** |
4 | ** The author disclaims copyright to this source code. In place of |
5 | ** a legal notice, here is a blessing: |
6 | ** |
7 | ** May you do good and not evil. |
8 | ** May you find forgiveness for yourself and forgive others. |
9 | ** May you share freely, never taking more than you give. |
10 | ** |
11 | ************************************************************************* |
12 | ** This header file defines the interface that the sqlite page cache |
13 | ** subsystem. |
14 | */ |
15 | |
16 | #ifndef _PCACHE_H_ |
17 | |
18 | typedef struct PgHdr PgHdr; |
19 | typedef struct PCache PCache; |
20 | |
21 | /* |
22 | ** Every page in the cache is controlled by an instance of the following |
23 | ** structure. |
24 | */ |
25 | struct PgHdr { |
26 | sqlite3_pcache_page *pPage; /* Pcache object page handle */ |
27 | void *pData; /* Page data */ |
28 | void *; /* Extra content */ |
29 | PCache *pCache; /* PRIVATE: Cache that owns this page */ |
30 | PgHdr *pDirty; /* Transient list of dirty sorted by pgno */ |
31 | Pager *; /* The pager this page is part of */ |
32 | Pgno pgno; /* Page number for this page */ |
33 | #ifdef SQLITE_CHECK_PAGES |
34 | u32 pageHash; /* Hash of page content */ |
35 | #endif |
36 | u16 flags; /* PGHDR flags defined below */ |
37 | |
38 | /********************************************************************** |
39 | ** Elements above, except pCache, are public. All that follow are |
40 | ** private to pcache.c and should not be accessed by other modules. |
41 | ** pCache is grouped with the public elements for efficiency. |
42 | */ |
43 | i16 nRef; /* Number of users of this page */ |
44 | PgHdr *pDirtyNext; /* Next element in list of dirty pages */ |
45 | PgHdr *pDirtyPrev; /* Previous element in list of dirty pages */ |
46 | /* NB: pDirtyNext and pDirtyPrev are undefined if the |
47 | ** PgHdr object is not dirty */ |
48 | }; |
49 | |
50 | /* Bit values for PgHdr.flags */ |
51 | #define PGHDR_CLEAN 0x001 /* Page not on the PCache.pDirty list */ |
52 | #define PGHDR_DIRTY 0x002 /* Page is on the PCache.pDirty list */ |
53 | #define PGHDR_WRITEABLE 0x004 /* Journaled and ready to modify */ |
54 | #define PGHDR_NEED_SYNC 0x008 /* Fsync the rollback journal before |
55 | ** writing this page to the database */ |
56 | #define PGHDR_DONT_WRITE 0x010 /* Do not write content to disk */ |
57 | #define PGHDR_MMAP 0x020 /* This is an mmap page object */ |
58 | |
59 | #define PGHDR_WAL_APPEND 0x040 /* Appended to wal file */ |
60 | |
61 | /* Initialize and shutdown the page cache subsystem */ |
62 | int sqlite3PcacheInitialize(void); |
63 | void sqlite3PcacheShutdown(void); |
64 | |
65 | /* Page cache buffer management: |
66 | ** These routines implement SQLITE_CONFIG_PAGECACHE. |
67 | */ |
68 | void sqlite3PCacheBufferSetup(void *, int sz, int n); |
69 | |
70 | /* Create a new pager cache. |
71 | ** Under memory stress, invoke xStress to try to make pages clean. |
72 | ** Only clean and unpinned pages can be reclaimed. |
73 | */ |
74 | int sqlite3PcacheOpen( |
75 | int szPage, /* Size of every page */ |
76 | int , /* Extra space associated with each page */ |
77 | int bPurgeable, /* True if pages are on backing store */ |
78 | int (*xStress)(void*, PgHdr*), /* Call to try to make pages clean */ |
79 | void *pStress, /* Argument to xStress */ |
80 | PCache *pToInit /* Preallocated space for the PCache */ |
81 | ); |
82 | |
83 | /* Modify the page-size after the cache has been created. */ |
84 | int sqlite3PcacheSetPageSize(PCache *, int); |
85 | |
86 | /* Return the size in bytes of a PCache object. Used to preallocate |
87 | ** storage space. |
88 | */ |
89 | int sqlite3PcacheSize(void); |
90 | |
91 | /* One release per successful fetch. Page is pinned until released. |
92 | ** Reference counted. |
93 | */ |
94 | sqlite3_pcache_page *sqlite3PcacheFetch(PCache*, Pgno, int createFlag); |
95 | int sqlite3PcacheFetchStress(PCache*, Pgno, sqlite3_pcache_page**); |
96 | PgHdr *sqlite3PcacheFetchFinish(PCache*, Pgno, sqlite3_pcache_page *pPage); |
97 | void sqlite3PcacheRelease(PgHdr*); |
98 | |
99 | void sqlite3PcacheDrop(PgHdr*); /* Remove page from cache */ |
100 | void sqlite3PcacheMakeDirty(PgHdr*); /* Make sure page is marked dirty */ |
101 | void sqlite3PcacheMakeClean(PgHdr*); /* Mark a single page as clean */ |
102 | void sqlite3PcacheCleanAll(PCache*); /* Mark all dirty list pages as clean */ |
103 | void sqlite3PcacheClearWritable(PCache*); |
104 | |
105 | /* Change a page number. Used by incr-vacuum. */ |
106 | void sqlite3PcacheMove(PgHdr*, Pgno); |
107 | |
108 | /* Remove all pages with pgno>x. Reset the cache if x==0 */ |
109 | void sqlite3PcacheTruncate(PCache*, Pgno x); |
110 | |
111 | /* Get a list of all dirty pages in the cache, sorted by page number */ |
112 | PgHdr *sqlite3PcacheDirtyList(PCache*); |
113 | |
114 | /* Reset and close the cache object */ |
115 | void sqlite3PcacheClose(PCache*); |
116 | |
117 | /* Clear flags from pages of the page cache */ |
118 | void sqlite3PcacheClearSyncFlags(PCache *); |
119 | |
120 | /* Discard the contents of the cache */ |
121 | void sqlite3PcacheClear(PCache*); |
122 | |
123 | /* Return the total number of outstanding page references */ |
124 | int sqlite3PcacheRefCount(PCache*); |
125 | |
126 | /* Increment the reference count of an existing page */ |
127 | void sqlite3PcacheRef(PgHdr*); |
128 | |
129 | int (PgHdr*); |
130 | |
131 | /* Return the total number of pages stored in the cache */ |
132 | int sqlite3PcachePagecount(PCache*); |
133 | |
134 | #if defined(SQLITE_CHECK_PAGES) || defined(SQLITE_DEBUG) |
135 | /* Iterate through all dirty pages currently stored in the cache. This |
136 | ** interface is only available if SQLITE_CHECK_PAGES is defined when the |
137 | ** library is built. |
138 | */ |
139 | void sqlite3PcacheIterateDirty(PCache *pCache, void (*xIter)(PgHdr *)); |
140 | #endif |
141 | |
142 | #if defined(SQLITE_DEBUG) |
143 | /* Check invariants on a PgHdr object */ |
144 | int sqlite3PcachePageSanity(PgHdr*); |
145 | #endif |
146 | |
147 | /* Set and get the suggested cache-size for the specified pager-cache. |
148 | ** |
149 | ** If no global maximum is configured, then the system attempts to limit |
150 | ** the total number of pages cached by purgeable pager-caches to the sum |
151 | ** of the suggested cache-sizes. |
152 | */ |
153 | void sqlite3PcacheSetCachesize(PCache *, int); |
154 | #ifdef SQLITE_TEST |
155 | int sqlite3PcacheGetCachesize(PCache *); |
156 | #endif |
157 | |
158 | /* Set or get the suggested spill-size for the specified pager-cache. |
159 | ** |
160 | ** The spill-size is the minimum number of pages in cache before the cache |
161 | ** will attempt to spill dirty pages by calling xStress. |
162 | */ |
163 | int sqlite3PcacheSetSpillsize(PCache *, int); |
164 | |
165 | /* Free up as much memory as possible from the page cache */ |
166 | void sqlite3PcacheShrink(PCache*); |
167 | |
168 | #ifdef SQLITE_ENABLE_MEMORY_MANAGEMENT |
169 | /* Try to return memory used by the pcache module to the main memory heap */ |
170 | int sqlite3PcacheReleaseMemory(int); |
171 | #endif |
172 | |
173 | #ifdef SQLITE_TEST |
174 | void sqlite3PcacheStats(int*,int*,int*,int*); |
175 | #endif |
176 | |
177 | void sqlite3PCacheSetDefault(void); |
178 | |
179 | /* Return the header size */ |
180 | int (void); |
181 | int (void); |
182 | |
183 | /* Number of dirty pages as a percentage of the configured cache size */ |
184 | int sqlite3PCachePercentDirty(PCache*); |
185 | |
186 | #ifdef SQLITE_DIRECT_OVERFLOW_READ |
187 | int sqlite3PCacheIsDirty(PCache *pCache); |
188 | #endif |
189 | |
190 | #endif /* _PCACHE_H_ */ |
191 | |