danielk1977 | 8c0a791 | 2008-08-20 14:49:23 +0000 | [diff] [blame] | 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 | ** |
danielk1977 | f3d3c27 | 2008-11-19 16:52:44 +0000 | [diff] [blame] | 15 | ** @(#) $Id: pcache.h,v 1.16 2008/11/19 16:52:44 danielk1977 Exp $ |
danielk1977 | 8c0a791 | 2008-08-20 14:49:23 +0000 | [diff] [blame] | 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 { |
danielk1977 | 8c0a791 | 2008-08-20 14:49:23 +0000 | [diff] [blame] | 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 */ |
drh | a85f7e3 | 2008-08-28 02:26:07 +0000 | [diff] [blame] | 32 | Pager *pPager; /* The pager this page is part of */ |
danielk1977 | 8c0a791 | 2008-08-20 14:49:23 +0000 | [diff] [blame] | 33 | #ifdef SQLITE_CHECK_PAGES |
drh | a85f7e3 | 2008-08-28 02:26:07 +0000 | [diff] [blame] | 34 | u32 pageHash; /* Hash of page content */ |
danielk1977 | 8c0a791 | 2008-08-20 14:49:23 +0000 | [diff] [blame] | 35 | #endif |
drh | a85f7e3 | 2008-08-28 02:26:07 +0000 | [diff] [blame] | 36 | u16 flags; /* PGHDR flags defined below */ |
danielk1977 | bc2ca9e | 2008-11-13 14:28:28 +0000 | [diff] [blame] | 37 | |
drh | a85f7e3 | 2008-08-28 02:26:07 +0000 | [diff] [blame] | 38 | /********************************************************************** |
| 39 | ** Elements above are public. All that follows is private to pcache.c |
| 40 | ** and should not be accessed by other modules. |
| 41 | */ |
| 42 | i16 nRef; /* Number of users of this page */ |
danielk1977 | 8c0a791 | 2008-08-20 14:49:23 +0000 | [diff] [blame] | 43 | PCache *pCache; /* Cache that owns this page */ |
danielk1977 | b317538 | 2008-10-17 18:51:52 +0000 | [diff] [blame] | 44 | |
danielk1977 | bc2ca9e | 2008-11-13 14:28:28 +0000 | [diff] [blame] | 45 | PgHdr *pDirtyNext; /* Next element in list of dirty pages */ |
| 46 | PgHdr *pDirtyPrev; /* Previous element in list of dirty pages */ |
danielk1977 | 8c0a791 | 2008-08-20 14:49:23 +0000 | [diff] [blame] | 47 | }; |
| 48 | |
| 49 | /* Bit values for PgHdr.flags */ |
drh | b3df2e1 | 2008-09-17 20:06:26 +0000 | [diff] [blame] | 50 | #define PGHDR_DIRTY 0x002 /* Page has changed */ |
| 51 | #define PGHDR_NEED_SYNC 0x004 /* Fsync the rollback journal before |
| 52 | ** writing this page to the database */ |
| 53 | #define PGHDR_NEED_READ 0x008 /* Content is unread */ |
| 54 | #define PGHDR_REUSE_UNLIKELY 0x010 /* A hint that reuse is unlikely */ |
| 55 | #define PGHDR_DONT_WRITE 0x020 /* Do not write content to disk */ |
danielk1977 | 8c0a791 | 2008-08-20 14:49:23 +0000 | [diff] [blame] | 56 | |
| 57 | /* Initialize and shutdown the page cache subsystem */ |
| 58 | int sqlite3PcacheInitialize(void); |
| 59 | void sqlite3PcacheShutdown(void); |
| 60 | |
| 61 | /* Page cache buffer management: |
| 62 | ** These routines implement SQLITE_CONFIG_PAGECACHE. |
| 63 | */ |
| 64 | void sqlite3PCacheBufferSetup(void *, int sz, int n); |
danielk1977 | 8c0a791 | 2008-08-20 14:49:23 +0000 | [diff] [blame] | 65 | |
| 66 | /* Create a new pager cache. |
| 67 | ** Under memory stress, invoke xStress to try to make pages clean. |
| 68 | ** Only clean and unpinned pages can be reclaimed. |
| 69 | */ |
| 70 | void sqlite3PcacheOpen( |
danielk1977 | a858aa2 | 2008-08-22 16:22:17 +0000 | [diff] [blame] | 71 | int szPage, /* Size of every page */ |
| 72 | int szExtra, /* Extra space associated with each page */ |
| 73 | int bPurgeable, /* True if pages are on backing store */ |
danielk1977 | a858aa2 | 2008-08-22 16:22:17 +0000 | [diff] [blame] | 74 | int (*xStress)(void*, PgHdr*), /* Call to try to make pages clean */ |
| 75 | void *pStress, /* Argument to xStress */ |
| 76 | PCache *pToInit /* Preallocated space for the PCache */ |
danielk1977 | 8c0a791 | 2008-08-20 14:49:23 +0000 | [diff] [blame] | 77 | ); |
| 78 | |
| 79 | /* Modify the page-size after the cache has been created. */ |
| 80 | void sqlite3PcacheSetPageSize(PCache *, int); |
| 81 | |
| 82 | /* Return the size in bytes of a PCache object. Used to preallocate |
| 83 | ** storage space. |
| 84 | */ |
| 85 | int sqlite3PcacheSize(void); |
| 86 | |
| 87 | /* One release per successful fetch. Page is pinned until released. |
| 88 | ** Reference counted. |
| 89 | */ |
| 90 | int sqlite3PcacheFetch(PCache*, Pgno, int createFlag, PgHdr**); |
| 91 | void sqlite3PcacheRelease(PgHdr*); |
| 92 | |
| 93 | void sqlite3PcacheDrop(PgHdr*); /* Remove page from cache */ |
| 94 | void sqlite3PcacheMakeDirty(PgHdr*); /* Make sure page is marked dirty */ |
| 95 | void sqlite3PcacheMakeClean(PgHdr*); /* Mark a single page as clean */ |
| 96 | void sqlite3PcacheCleanAll(PCache*); /* Mark all dirty list pages as clean */ |
| 97 | |
| 98 | /* Change a page number. Used by incr-vacuum. */ |
| 99 | void sqlite3PcacheMove(PgHdr*, Pgno); |
| 100 | |
danielk1977 | 8c0a791 | 2008-08-20 14:49:23 +0000 | [diff] [blame] | 101 | /* Remove all pages with pgno>x. Reset the cache if x==0 */ |
| 102 | void sqlite3PcacheTruncate(PCache*, Pgno x); |
| 103 | |
danielk1977 | 8c0a791 | 2008-08-20 14:49:23 +0000 | [diff] [blame] | 104 | /* Get a list of all dirty pages in the cache, sorted by page number */ |
| 105 | PgHdr *sqlite3PcacheDirtyList(PCache*); |
| 106 | |
danielk1977 | 8c0a791 | 2008-08-20 14:49:23 +0000 | [diff] [blame] | 107 | /* Reset and close the cache object */ |
| 108 | void sqlite3PcacheClose(PCache*); |
| 109 | |
drh | b3df2e1 | 2008-09-17 20:06:26 +0000 | [diff] [blame] | 110 | /* Clear flags from pages of the page cache */ |
danielk1977 | bc2ca9e | 2008-11-13 14:28:28 +0000 | [diff] [blame] | 111 | void sqlite3PcacheClearSyncFlags(PCache *); |
danielk1977 | 8c0a791 | 2008-08-20 14:49:23 +0000 | [diff] [blame] | 112 | |
danielk1977 | 8c0a791 | 2008-08-20 14:49:23 +0000 | [diff] [blame] | 113 | /* Discard the contents of the cache */ |
| 114 | int sqlite3PcacheClear(PCache*); |
| 115 | |
| 116 | /* Return the total number of outstanding page references */ |
| 117 | int sqlite3PcacheRefCount(PCache*); |
| 118 | |
| 119 | /* Increment the reference count of an existing page */ |
| 120 | void sqlite3PcacheRef(PgHdr*); |
| 121 | |
danielk1977 | 71d5d2c | 2008-09-29 11:49:47 +0000 | [diff] [blame] | 122 | int sqlite3PcachePageRefcount(PgHdr*); |
| 123 | |
danielk1977 | 8c0a791 | 2008-08-20 14:49:23 +0000 | [diff] [blame] | 124 | /* Return the total number of pages stored in the cache */ |
| 125 | int sqlite3PcachePagecount(PCache*); |
| 126 | |
drh | 419fcf6 | 2008-10-11 17:42:28 +0000 | [diff] [blame] | 127 | #ifdef SQLITE_CHECK_PAGES |
danielk1977 | bc2ca9e | 2008-11-13 14:28:28 +0000 | [diff] [blame] | 128 | /* Iterate through all dirty pages currently stored in the cache. This |
| 129 | ** interface is only available if SQLITE_CHECK_PAGES is defined when the |
| 130 | ** library is built. |
danielk1977 | 8c0a791 | 2008-08-20 14:49:23 +0000 | [diff] [blame] | 131 | */ |
danielk1977 | bc2ca9e | 2008-11-13 14:28:28 +0000 | [diff] [blame] | 132 | void sqlite3PcacheIterateDirty(PCache *pCache, void (*xIter)(PgHdr *)); |
drh | 419fcf6 | 2008-10-11 17:42:28 +0000 | [diff] [blame] | 133 | #endif |
danielk1977 | 8c0a791 | 2008-08-20 14:49:23 +0000 | [diff] [blame] | 134 | |
danielk1977 | d491e1b | 2008-08-26 18:05:48 +0000 | [diff] [blame] | 135 | /* Set and get the suggested cache-size for the specified pager-cache. |
danielk1977 | 8c0a791 | 2008-08-20 14:49:23 +0000 | [diff] [blame] | 136 | ** |
| 137 | ** If no global maximum is configured, then the system attempts to limit |
| 138 | ** the total number of pages cached by purgeable pager-caches to the sum |
| 139 | ** of the suggested cache-sizes. |
| 140 | */ |
danielk1977 | 8c0a791 | 2008-08-20 14:49:23 +0000 | [diff] [blame] | 141 | void sqlite3PcacheSetCachesize(PCache *, int); |
danielk1977 | f3d3c27 | 2008-11-19 16:52:44 +0000 | [diff] [blame] | 142 | #ifdef SQLITE_TEST |
| 143 | int sqlite3PcacheGetCachesize(PCache *); |
| 144 | #endif |
danielk1977 | 8c0a791 | 2008-08-20 14:49:23 +0000 | [diff] [blame] | 145 | |
drh | 419fcf6 | 2008-10-11 17:42:28 +0000 | [diff] [blame] | 146 | #ifdef SQLITE_ENABLE_MEMORY_MANAGEMENT |
danielk1977 | d491e1b | 2008-08-26 18:05:48 +0000 | [diff] [blame] | 147 | /* Try to return memory used by the pcache module to the main memory heap */ |
danielk1977 | 67e3da7 | 2008-08-21 12:19:44 +0000 | [diff] [blame] | 148 | int sqlite3PcacheReleaseMemory(int); |
drh | 419fcf6 | 2008-10-11 17:42:28 +0000 | [diff] [blame] | 149 | #endif |
danielk1977 | 67e3da7 | 2008-08-21 12:19:44 +0000 | [diff] [blame] | 150 | |
drh | 419fcf6 | 2008-10-11 17:42:28 +0000 | [diff] [blame] | 151 | #ifdef SQLITE_TEST |
danielk1977 | 062d4cb | 2008-08-29 09:10:02 +0000 | [diff] [blame] | 152 | void sqlite3PcacheStats(int*,int*,int*,int*); |
drh | 419fcf6 | 2008-10-11 17:42:28 +0000 | [diff] [blame] | 153 | #endif |
danielk1977 | 062d4cb | 2008-08-29 09:10:02 +0000 | [diff] [blame] | 154 | |
danielk1977 | bc2ca9e | 2008-11-13 14:28:28 +0000 | [diff] [blame] | 155 | void sqlite3PCacheSetDefault(void); |
| 156 | |
danielk1977 | 8c0a791 | 2008-08-20 14:49:23 +0000 | [diff] [blame] | 157 | #endif /* _PCACHE_H_ */ |