third_party/sqlite/sqlite-src-3080704/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   PgHdr *pDirty;                 /* Transient list of dirty pages */
  30   Pager *pPager;                 /* The pager this page is part of */
  31   Pgno pgno;                     /* Page number for this page */
  32 #ifdef SQLITE_CHECK_PAGES
  33   u32 pageHash;                  /* Hash of page content */
  34 #endif
  35   u16 flags;                     /* PGHDR flags defined below */
  36
  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
  44   PgHdr *pDirtyNext;             /* Next element in list of dirty pages */
  45   PgHdr *pDirtyPrev;             /* Previous element in list of dirty pages */
  46 };
  47
  48 /* Bit values for PgHdr.flags */
  49 #define PGHDR_DIRTY             0x002  /* Page has changed */
  50 #define PGHDR_NEED_SYNC         0x004  /* Fsync the rollback journal before
  51                                        ** writing this page to the database */
  52 #define PGHDR_NEED_READ         0x008  /* Content is unread */
  53 #define PGHDR_REUSE_UNLIKELY    0x010  /* A hint that reuse is unlikely */
  54 #define PGHDR_DONT_WRITE        0x020  /* Do not write content to disk */
  55
  56 #define PGHDR_MMAP              0x040  /* This is an mmap page object */
  57
  58 /* Initialize and shutdown the page cache subsystem */
  59 int sqlite3PcacheInitialize(void);
  60 void sqlite3PcacheShutdown(void);
  61
  62 /* Page cache buffer management:
  63 ** These routines implement SQLITE_CONFIG_PAGECACHE.
  64 */
  65 void sqlite3PCacheBufferSetup(void *, int sz, int n);
  66
  67 /* Create a new pager cache.
  68 ** Under memory stress, invoke xStress to try to make pages clean.
  69 ** Only clean and unpinned pages can be reclaimed.
  70 */
  71 int sqlite3PcacheOpen(
  72   int szPage,                    /* Size of every page */
  73   int szExtra,                   /* Extra space associated with each page */
  74   int bPurgeable,                /* True if pages are on backing store */
  75   int (*xStress)(void*, PgHdr*), /* Call to try to make pages clean */
  76   void *pStress,                 /* Argument to xStress */
  77   PCache *pToInit                /* Preallocated space for the PCache */
  78 );
  79
  80 /* Modify the page-size after the cache has been created. */
  81 int sqlite3PcacheSetPageSize(PCache *, int);
  82
  83 /* Return the size in bytes of a PCache object.  Used to preallocate
  84 ** storage space.
  85 */
  86 int sqlite3PcacheSize(void);
  87
  88 /* One release per successful fetch.  Page is pinned until released.
  89 ** Reference counted.
  90 */
  91 sqlite3_pcache_page *sqlite3PcacheFetch(PCache*, Pgno, int createFlag);
  92 int sqlite3PcacheFetchStress(PCache*, Pgno, sqlite3_pcache_page**);
  93 PgHdr *sqlite3PcacheFetchFinish(PCache*, Pgno, sqlite3_pcache_page *pPage);
  94 void sqlite3PcacheRelease(PgHdr*);
  95
  96 void sqlite3PcacheDrop(PgHdr*);         /* Remove page from cache */
  97 void sqlite3PcacheMakeDirty(PgHdr*);    /* Make sure page is marked dirty */
  98 void sqlite3PcacheMakeClean(PgHdr*);    /* Mark a single page as clean */
  99 void sqlite3PcacheCleanAll(PCache*);    /* Mark all dirty list pages as clean */
 100
 101 /* Change a page number.  Used by incr-vacuum. */
 102 void sqlite3PcacheMove(PgHdr*, Pgno);
 103
 104 /* Remove all pages with pgno>x.  Reset the cache if x==0 */
 105 void sqlite3PcacheTruncate(PCache*, Pgno x);
 106
 107 /* Get a list of all dirty pages in the cache, sorted by page number */
 108 PgHdr *sqlite3PcacheDirtyList(PCache*);
 109
 110 /* Reset and close the cache object */
 111 void sqlite3PcacheClose(PCache*);
 112
 113 /* Clear flags from pages of the page cache */
 114 void sqlite3PcacheClearSyncFlags(PCache *);
 115
 116 /* Discard the contents of the cache */
 117 void sqlite3PcacheClear(PCache*);
 118
 119 /* Return the total number of outstanding page references */
 120 int sqlite3PcacheRefCount(PCache*);
 121
 122 /* Increment the reference count of an existing page */
 123 void sqlite3PcacheRef(PgHdr*);
 124
 125 int sqlite3PcachePageRefcount(PgHdr*);
 126
 127 /* Return the total number of pages stored in the cache */
 128 int sqlite3PcachePagecount(PCache*);
 129
 130 #if defined(SQLITE_CHECK_PAGES) || defined(SQLITE_DEBUG)
 131 /* Iterate through all dirty pages currently stored in the cache. This
 132 ** interface is only available if SQLITE_CHECK_PAGES is defined when the
 133 ** library is built.
 134 */
 135 void sqlite3PcacheIterateDirty(PCache *pCache, void (*xIter)(PgHdr *));
 136 #endif
 137
 138 /* Set and get the suggested cache-size for the specified pager-cache.
 139 **
 140 ** If no global maximum is configured, then the system attempts to limit
 141 ** the total number of pages cached by purgeable pager-caches to the sum
 142 ** of the suggested cache-sizes.
 143 */
 144 void sqlite3PcacheSetCachesize(PCache *, int);
 145 #ifdef SQLITE_TEST
 146 int sqlite3PcacheGetCachesize(PCache *);
 147 #endif
 148
 149 /* Free up as much memory as possible from the page cache */
 150 void sqlite3PcacheShrink(PCache*);
 151
 152 #ifdef SQLITE_ENABLE_MEMORY_MANAGEMENT
 153 /* Try to return memory used by the pcache module to the main memory heap */
 154 int sqlite3PcacheReleaseMemory(int);
 155 #endif
 156
 157 #ifdef SQLITE_TEST
 158 void sqlite3PcacheStats(int*,int*,int*,int*);
 159 #endif
 160
 161 void sqlite3PCacheSetDefault(void);
 162
 163 #endif /* _PCACHE_H_ */