4 ** The author disclaims copyright to this source code. In place of
5 ** a legal notice, here is a blessing:
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
15 ** @(#) $Id: pcache.h,v 1.13 2008/10/11 17:42:29 drh Exp $
20 typedef struct PgHdr PgHdr;
21 typedef struct PCache PCache;
24 ** Every page in the cache is controlled by an instance of the following
28 void *pData; /* Content of this page */
29 void *pExtra; /* Extra content */
30 PgHdr *pDirty; /* Transient list of dirty pages */
31 Pgno pgno; /* Page number for this page */
32 Pager *pPager; /* The pager this page is part of */
33 #ifdef SQLITE_CHECK_PAGES
34 u32 pageHash; /* Hash of page content */
36 u16 flags; /* PGHDR flags defined below */
37 /**********************************************************************
38 ** Elements above are public. All that follows is private to pcache.c
39 ** and should not be accessed by other modules.
41 i16 nRef; /* Number of users of this page */
42 PCache *pCache; /* Cache that owns this page */
43 void *apSave[2]; /* Journal entries for in-memory databases */
44 /**********************************************************************
45 ** Elements above are accessible at any time by the owner of the cache
46 ** without the need for a mutex. The elements that follow can only be
47 ** accessed while holding the SQLITE_MUTEX_STATIC_LRU mutex.
49 PgHdr *pNextHash, *pPrevHash; /* Hash collision chain for PgHdr.pgno */
50 PgHdr *pNext, *pPrev; /* List of clean or dirty pages */
51 PgHdr *pNextLru, *pPrevLru; /* Part of global LRU list */
54 /* Bit values for PgHdr.flags */
55 #define PGHDR_IN_JOURNAL 0x001 /* Page is in rollback journal */
56 #define PGHDR_DIRTY 0x002 /* Page has changed */
57 #define PGHDR_NEED_SYNC 0x004 /* Fsync the rollback journal before
58 ** writing this page to the database */
59 #define PGHDR_NEED_READ 0x008 /* Content is unread */
60 #define PGHDR_REUSE_UNLIKELY 0x010 /* A hint that reuse is unlikely */
61 #define PGHDR_DONT_WRITE 0x020 /* Do not write content to disk */
63 /* Initialize and shutdown the page cache subsystem */
64 int sqlite3PcacheInitialize(void);
65 void sqlite3PcacheShutdown(void);
67 /* Page cache buffer management:
68 ** These routines implement SQLITE_CONFIG_PAGECACHE.
70 void sqlite3PCacheBufferSetup(void *, int sz, int n);
71 void *sqlite3PCacheMalloc(int sz);
72 void sqlite3PCacheFree(void*);
74 /* Create a new pager cache.
75 ** Under memory stress, invoke xStress to try to make pages clean.
76 ** Only clean and unpinned pages can be reclaimed.
78 void sqlite3PcacheOpen(
79 int szPage, /* Size of every page */
80 int szExtra, /* Extra space associated with each page */
81 int bPurgeable, /* True if pages are on backing store */
82 int (*xStress)(void*, PgHdr*), /* Call to try to make pages clean */
83 void *pStress, /* Argument to xStress */
84 PCache *pToInit /* Preallocated space for the PCache */
87 /* Modify the page-size after the cache has been created. */
88 void sqlite3PcacheSetPageSize(PCache *, int);
90 /* Return the size in bytes of a PCache object. Used to preallocate
93 int sqlite3PcacheSize(void);
95 /* One release per successful fetch. Page is pinned until released.
98 int sqlite3PcacheFetch(PCache*, Pgno, int createFlag, PgHdr**);
99 void sqlite3PcacheRelease(PgHdr*);
101 void sqlite3PcacheDrop(PgHdr*); /* Remove page from cache */
102 void sqlite3PcacheMakeDirty(PgHdr*); /* Make sure page is marked dirty */
103 void sqlite3PcacheMakeClean(PgHdr*); /* Mark a single page as clean */
104 void sqlite3PcacheCleanAll(PCache*); /* Mark all dirty list pages as clean */
106 /* Change a page number. Used by incr-vacuum. */
107 void sqlite3PcacheMove(PgHdr*, Pgno);
109 /* Remove all pages with pgno>x. Reset the cache if x==0 */
110 void sqlite3PcacheTruncate(PCache*, Pgno x);
112 /* Routines used to implement transactions on memory-only databases. */
113 int sqlite3PcachePreserve(PgHdr*, int); /* Preserve current page content */
114 void sqlite3PcacheCommit(PCache*, int); /* Drop preserved copy */
115 void sqlite3PcacheRollback(PCache*, int, void (*xReiniter)(PgHdr*));
117 /* Get a list of all dirty pages in the cache, sorted by page number */
118 PgHdr *sqlite3PcacheDirtyList(PCache*);
120 /* Reset and close the cache object */
121 void sqlite3PcacheClose(PCache*);
123 /* Clear flags from pages of the page cache */
124 void sqlite3PcacheClearFlags(PCache*, int mask);
126 /* Assert flags settings on all pages. Debugging only */
128 void sqlite3PcacheAssertFlags(PCache*, int trueMask, int falseMask);
130 # define sqlite3PcacheAssertFlags(A,B,C)
133 /* Return true if the number of dirty pages is 0 or 1 */
134 int sqlite3PcacheZeroOrOneDirtyPages(PCache*);
136 /* Discard the contents of the cache */
137 int sqlite3PcacheClear(PCache*);
139 /* Return the total number of outstanding page references */
140 int sqlite3PcacheRefCount(PCache*);
142 /* Increment the reference count of an existing page */
143 void sqlite3PcacheRef(PgHdr*);
145 int sqlite3PcachePageRefcount(PgHdr*);
147 /* Return the total number of pages stored in the cache */
148 int sqlite3PcachePagecount(PCache*);
150 #ifdef SQLITE_CHECK_PAGES
151 /* Iterate through all pages currently stored in the cache. This interface
152 ** is only available if SQLITE_CHECK_PAGES is defined when the library is
155 void sqlite3PcacheIterate(PCache *pCache, void (*xIter)(PgHdr *));
158 /* Set and get the suggested cache-size for the specified pager-cache.
160 ** If no global maximum is configured, then the system attempts to limit
161 ** the total number of pages cached by purgeable pager-caches to the sum
162 ** of the suggested cache-sizes.
164 int sqlite3PcacheGetCachesize(PCache *);
165 void sqlite3PcacheSetCachesize(PCache *, int);
167 #ifdef SQLITE_ENABLE_MEMORY_MANAGEMENT
168 /* Try to return memory used by the pcache module to the main memory heap */
169 int sqlite3PcacheReleaseMemory(int);
173 void sqlite3PcacheStats(int*,int*,int*,int*);
176 #endif /* _PCACHE_H_ */