Make the walIndexPage() routine about 3x faster by factoring out the seldom
[sqlite.git] / src / pcache.h
blobbbc2cb453984e1e7c732b8a7672dc026998a295c
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.
11 *************************************************************************
12 ** This header file defines the interface that the sqlite page cache
13 ** subsystem.
16 #ifndef _PCACHE_H_
18 typedef struct PgHdr PgHdr;
19 typedef struct PCache PCache;
22 ** Every page in the cache is controlled by an instance of the following
23 ** structure.
25 struct PgHdr {
26 sqlite3_pcache_page *pPage; /* Pcache object page handle */
27 void *pData; /* Page data */
28 void *pExtra; /* Extra content */
29 PCache *pCache; /* PRIVATE: Cache that owns this page */
30 PgHdr *pDirty; /* Transient list of dirty sorted by pgno */
31 Pager *pPager; /* 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 */
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.
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 */
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 */
59 #define PGHDR_WAL_APPEND 0x040 /* Appended to wal file */
61 /* Initialize and shutdown the page cache subsystem */
62 int sqlite3PcacheInitialize(void);
63 void sqlite3PcacheShutdown(void);
65 /* Page cache buffer management:
66 ** These routines implement SQLITE_CONFIG_PAGECACHE.
68 void sqlite3PCacheBufferSetup(void *, int sz, int n);
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.
74 int sqlite3PcacheOpen(
75 int szPage, /* Size of every page */
76 int szExtra, /* 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 */
83 /* Modify the page-size after the cache has been created. */
84 int sqlite3PcacheSetPageSize(PCache *, int);
86 /* Return the size in bytes of a PCache object. Used to preallocate
87 ** storage space.
89 int sqlite3PcacheSize(void);
91 /* One release per successful fetch. Page is pinned until released.
92 ** Reference counted.
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*);
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*);
105 /* Change a page number. Used by incr-vacuum. */
106 void sqlite3PcacheMove(PgHdr*, Pgno);
108 /* Remove all pages with pgno>x. Reset the cache if x==0 */
109 void sqlite3PcacheTruncate(PCache*, Pgno x);
111 /* Get a list of all dirty pages in the cache, sorted by page number */
112 PgHdr *sqlite3PcacheDirtyList(PCache*);
114 /* Reset and close the cache object */
115 void sqlite3PcacheClose(PCache*);
117 /* Clear flags from pages of the page cache */
118 void sqlite3PcacheClearSyncFlags(PCache *);
120 /* Discard the contents of the cache */
121 void sqlite3PcacheClear(PCache*);
123 /* Return the total number of outstanding page references */
124 int sqlite3PcacheRefCount(PCache*);
126 /* Increment the reference count of an existing page */
127 void sqlite3PcacheRef(PgHdr*);
129 int sqlite3PcachePageRefcount(PgHdr*);
131 /* Return the total number of pages stored in the cache */
132 int sqlite3PcachePagecount(PCache*);
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.
139 void sqlite3PcacheIterateDirty(PCache *pCache, void (*xIter)(PgHdr *));
140 #endif
142 #if defined(SQLITE_DEBUG)
143 /* Check invariants on a PgHdr object */
144 int sqlite3PcachePageSanity(PgHdr*);
145 #endif
147 /* Set and get the suggested cache-size for the specified pager-cache.
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.
153 void sqlite3PcacheSetCachesize(PCache *, int);
154 #ifdef SQLITE_TEST
155 int sqlite3PcacheGetCachesize(PCache *);
156 #endif
158 /* Set or get the suggested spill-size for the specified pager-cache.
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.
163 int sqlite3PcacheSetSpillsize(PCache *, int);
165 /* Free up as much memory as possible from the page cache */
166 void sqlite3PcacheShrink(PCache*);
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
173 #ifdef SQLITE_TEST
174 void sqlite3PcacheStats(int*,int*,int*,int*);
175 #endif
177 void sqlite3PCacheSetDefault(void);
179 /* Return the header size */
180 int sqlite3HeaderSizePcache(void);
181 int sqlite3HeaderSizePcache1(void);
183 /* Number of dirty pages as a percentage of the configured cache size */
184 int sqlite3PCachePercentDirty(PCache*);
186 #endif /* _PCACHE_H_ */