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 void 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 void 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 int sqlite3PcacheFetch(PCache*, Pgno, int createFlag, PgHdr**);
  92 void sqlite3PcacheRelease(PgHdr*);
  93
  94 void sqlite3PcacheDrop(PgHdr*);         /* Remove page from cache */
  95 void sqlite3PcacheMakeDirty(PgHdr*);    /* Make sure page is marked dirty */
  96 void sqlite3PcacheMakeClean(PgHdr*);    /* Mark a single page as clean */
  97 void sqlite3PcacheCleanAll(PCache*);    /* Mark all dirty list pages as clean */
  98
  99 /* Change a page number.  Used by incr-vacuum. */
 100 void sqlite3PcacheMove(PgHdr*, Pgno);
 101
 102 /* Remove all pages with pgno>x.  Reset the cache if x==0 */
 103 void sqlite3PcacheTruncate(PCache*, Pgno x);
 104
 105 /* Get a list of all dirty pages in the cache, sorted by page number */
 106 PgHdr *sqlite3PcacheDirtyList(PCache*);
 107
 108 /* Reset and close the cache object */
 109 void sqlite3PcacheClose(PCache*);
 110
 111 /* Clear flags from pages of the page cache */
 112 void sqlite3PcacheClearSyncFlags(PCache *);
 113
 114 /* Discard the contents of the cache */
 115 void sqlite3PcacheClear(PCache*);
 116
 117 /* Return the total number of outstanding page references */
 118 int sqlite3PcacheRefCount(PCache*);
 119
 120 /* Increment the reference count of an existing page */
 121 void sqlite3PcacheRef(PgHdr*);
 122
 123 int sqlite3PcachePageRefcount(PgHdr*);
 124
 125 /* Return the total number of pages stored in the cache */
 126 int sqlite3PcachePagecount(PCache*);
 127
 128 #if defined(SQLITE_CHECK_PAGES) || defined(SQLITE_DEBUG)
 129 /* Iterate through all dirty pages currently stored in the cache. This
 130 ** interface is only available if SQLITE_CHECK_PAGES is defined when the
 131 ** library is built.
 132 */
 133 void sqlite3PcacheIterateDirty(PCache *pCache, void (*xIter)(PgHdr *));
 134 #endif
 135
 136 /* Set and get the suggested cache-size for the specified pager-cache.
 137 **
 138 ** If no global maximum is configured, then the system attempts to limit
 139 ** the total number of pages cached by purgeable pager-caches to the sum
 140 ** of the suggested cache-sizes.
 141 */
 142 void sqlite3PcacheSetCachesize(PCache *, int);
 143 #ifdef SQLITE_TEST
 144 int sqlite3PcacheGetCachesize(PCache *);
 145 #endif
 146
 147 /* Free up as much memory as possible from the page cache */
 148 void sqlite3PcacheShrink(PCache*);
 149
 150 #ifdef SQLITE_ENABLE_MEMORY_MANAGEMENT
 151 /* Try to return memory used by the pcache module to the main memory heap */
 152 int sqlite3PcacheReleaseMemory(int);
 153 #endif
 154
 155 #ifdef SQLITE_TEST
 156 void sqlite3PcacheStats(int*,int*,int*,int*);
 157 #endif
 158
 159 void sqlite3PCacheSetDefault(void);
 160
 161 #endif /* _PCACHE_H_ */