|
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 ** @(#) $Id: pcache.h,v 1.12 2008/09/29 11:49:48 danielk1977 Exp $ |
|
16 */ |
|
17 |
|
18 #ifndef _PCACHE_H_ |
|
19 |
|
20 typedef struct PgHdr PgHdr; |
|
21 typedef struct PCache PCache; |
|
22 |
|
23 /* |
|
24 ** Every page in the cache is controlled by an instance of the following |
|
25 ** structure. |
|
26 */ |
|
27 struct PgHdr { |
|
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 */ |
|
35 #endif |
|
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. |
|
40 */ |
|
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. |
|
48 */ |
|
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 */ |
|
52 }; |
|
53 |
|
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 */ |
|
62 |
|
63 /* Initialize and shutdown the page cache subsystem */ |
|
64 int sqlite3PcacheInitialize(void); |
|
65 void sqlite3PcacheShutdown(void); |
|
66 |
|
67 /* Page cache buffer management: |
|
68 ** These routines implement SQLITE_CONFIG_PAGECACHE. |
|
69 */ |
|
70 void sqlite3PCacheBufferSetup(void *, int sz, int n); |
|
71 void *sqlite3PCacheMalloc(int sz); |
|
72 void sqlite3PCacheFree(void*); |
|
73 |
|
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. |
|
77 */ |
|
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 */ |
|
85 ); |
|
86 |
|
87 /* Modify the page-size after the cache has been created. */ |
|
88 void sqlite3PcacheSetPageSize(PCache *, int); |
|
89 |
|
90 /* Return the size in bytes of a PCache object. Used to preallocate |
|
91 ** storage space. |
|
92 */ |
|
93 int sqlite3PcacheSize(void); |
|
94 |
|
95 /* One release per successful fetch. Page is pinned until released. |
|
96 ** Reference counted. |
|
97 */ |
|
98 int sqlite3PcacheFetch(PCache*, Pgno, int createFlag, PgHdr**); |
|
99 void sqlite3PcacheRelease(PgHdr*); |
|
100 |
|
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 */ |
|
105 |
|
106 /* Change a page number. Used by incr-vacuum. */ |
|
107 void sqlite3PcacheMove(PgHdr*, Pgno); |
|
108 |
|
109 /* Remove all pages with pgno>x. Reset the cache if x==0 */ |
|
110 void sqlite3PcacheTruncate(PCache*, Pgno x); |
|
111 |
|
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*)); |
|
116 |
|
117 /* Get a list of all dirty pages in the cache, sorted by page number */ |
|
118 PgHdr *sqlite3PcacheDirtyList(PCache*); |
|
119 |
|
120 /* Reset and close the cache object */ |
|
121 void sqlite3PcacheClose(PCache*); |
|
122 |
|
123 /* Clear flags from pages of the page cache */ |
|
124 void sqlite3PcacheClearFlags(PCache*, int mask); |
|
125 |
|
126 /* Assert flags settings on all pages. Debugging only */ |
|
127 #ifndef NDEBUG |
|
128 void sqlite3PcacheAssertFlags(PCache*, int trueMask, int falseMask); |
|
129 #else |
|
130 # define sqlite3PcacheAssertFlags(A,B,C) |
|
131 #endif |
|
132 |
|
133 /* Return true if the number of dirty pages is 0 or 1 */ |
|
134 int sqlite3PcacheZeroOrOneDirtyPages(PCache*); |
|
135 |
|
136 /* Discard the contents of the cache */ |
|
137 int sqlite3PcacheClear(PCache*); |
|
138 |
|
139 /* Return the total number of outstanding page references */ |
|
140 int sqlite3PcacheRefCount(PCache*); |
|
141 |
|
142 /* Increment the reference count of an existing page */ |
|
143 void sqlite3PcacheRef(PgHdr*); |
|
144 |
|
145 int sqlite3PcachePageRefcount(PgHdr*); |
|
146 |
|
147 /* Return the total number of pages stored in the cache */ |
|
148 int sqlite3PcachePagecount(PCache*); |
|
149 |
|
150 /* Iterate through all pages currently stored in the cache. This interface |
|
151 ** is only available if SQLITE_CHECK_PAGES is defined when the library is |
|
152 ** built. |
|
153 */ |
|
154 void sqlite3PcacheIterate(PCache *pCache, void (*xIter)(PgHdr *)); |
|
155 |
|
156 /* Set and get the suggested cache-size for the specified pager-cache. |
|
157 ** |
|
158 ** If no global maximum is configured, then the system attempts to limit |
|
159 ** the total number of pages cached by purgeable pager-caches to the sum |
|
160 ** of the suggested cache-sizes. |
|
161 */ |
|
162 int sqlite3PcacheGetCachesize(PCache *); |
|
163 void sqlite3PcacheSetCachesize(PCache *, int); |
|
164 |
|
165 /* Try to return memory used by the pcache module to the main memory heap */ |
|
166 int sqlite3PcacheReleaseMemory(int); |
|
167 |
|
168 void sqlite3PcacheStats(int*,int*,int*,int*); |
|
169 |
|
170 #endif /* _PCACHE_H_ */ |