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 *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 */ 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 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 */ 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 sqlite3PcachePageRefcount(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 sqlite3HeaderSizePcache(void); 181 int sqlite3HeaderSizePcache1(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