src/pcache.h

   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 #endif /* _PCACHE_H_ */