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