sl@0: /*
sl@0: ** 2008 August 05
sl@0: **
sl@0: ** The author disclaims copyright to this source code.  In place of
sl@0: ** a legal notice, here is a blessing:
sl@0: **
sl@0: **    May you do good and not evil.
sl@0: **    May you find forgiveness for yourself and forgive others.
sl@0: **    May you share freely, never taking more than you give.
sl@0: **
sl@0: *************************************************************************
sl@0: ** This header file defines the interface that the sqlite page cache
sl@0: ** subsystem. 
sl@0: **
sl@0: ** @(#) $Id: pcache.h,v 1.13 2008/10/11 17:42:29 drh Exp $
sl@0: */
sl@0: 
sl@0: #ifndef _PCACHE_H_
sl@0: 
sl@0: typedef struct PgHdr PgHdr;
sl@0: typedef struct PCache PCache;
sl@0: 
sl@0: /*
sl@0: ** Every page in the cache is controlled by an instance of the following
sl@0: ** structure.
sl@0: */
sl@0: struct PgHdr {
sl@0:   void *pData;                   /* Content of this page */
sl@0:   void *pExtra;                  /* Extra content */
sl@0:   PgHdr *pDirty;                 /* Transient list of dirty pages */
sl@0:   Pgno pgno;                     /* Page number for this page */
sl@0:   Pager *pPager;                 /* The pager this page is part of */
sl@0: #ifdef SQLITE_CHECK_PAGES
sl@0:   u32 pageHash;                  /* Hash of page content */
sl@0: #endif
sl@0:   u16 flags;                     /* PGHDR flags defined below */
sl@0:   /**********************************************************************
sl@0:   ** Elements above are public.  All that follows is private to pcache.c
sl@0:   ** and should not be accessed by other modules.
sl@0:   */
sl@0:   i16 nRef;                      /* Number of users of this page */
sl@0:   PCache *pCache;                /* Cache that owns this page */
sl@0:   void *apSave[2];               /* Journal entries for in-memory databases */
sl@0:   /**********************************************************************
sl@0:   ** Elements above are accessible at any time by the owner of the cache
sl@0:   ** without the need for a mutex.  The elements that follow can only be
sl@0:   ** accessed while holding the SQLITE_MUTEX_STATIC_LRU mutex.
sl@0:   */
sl@0:   PgHdr *pNextHash, *pPrevHash;  /* Hash collision chain for PgHdr.pgno */
sl@0:   PgHdr *pNext, *pPrev;          /* List of clean or dirty pages */
sl@0:   PgHdr *pNextLru, *pPrevLru;    /* Part of global LRU list */
sl@0: };
sl@0: 
sl@0: /* Bit values for PgHdr.flags */
sl@0: #define PGHDR_IN_JOURNAL        0x001  /* Page is in rollback journal */
sl@0: #define PGHDR_DIRTY             0x002  /* Page has changed */
sl@0: #define PGHDR_NEED_SYNC         0x004  /* Fsync the rollback journal before
sl@0:                                        ** writing this page to the database */
sl@0: #define PGHDR_NEED_READ         0x008  /* Content is unread */
sl@0: #define PGHDR_REUSE_UNLIKELY    0x010  /* A hint that reuse is unlikely */
sl@0: #define PGHDR_DONT_WRITE        0x020  /* Do not write content to disk */
sl@0: 
sl@0: /* Initialize and shutdown the page cache subsystem */
sl@0: int sqlite3PcacheInitialize(void);
sl@0: void sqlite3PcacheShutdown(void);
sl@0: 
sl@0: /* Page cache buffer management:
sl@0: ** These routines implement SQLITE_CONFIG_PAGECACHE.
sl@0: */
sl@0: void sqlite3PCacheBufferSetup(void *, int sz, int n);
sl@0: void *sqlite3PCacheMalloc(int sz);
sl@0: void sqlite3PCacheFree(void*);
sl@0: 
sl@0: /* Create a new pager cache.
sl@0: ** Under memory stress, invoke xStress to try to make pages clean.
sl@0: ** Only clean and unpinned pages can be reclaimed.
sl@0: */
sl@0: void sqlite3PcacheOpen(
sl@0:   int szPage,                    /* Size of every page */
sl@0:   int szExtra,                   /* Extra space associated with each page */
sl@0:   int bPurgeable,                /* True if pages are on backing store */
sl@0:   int (*xStress)(void*, PgHdr*), /* Call to try to make pages clean */
sl@0:   void *pStress,                 /* Argument to xStress */
sl@0:   PCache *pToInit                /* Preallocated space for the PCache */
sl@0: );
sl@0: 
sl@0: /* Modify the page-size after the cache has been created. */
sl@0: void sqlite3PcacheSetPageSize(PCache *, int);
sl@0: 
sl@0: /* Return the size in bytes of a PCache object.  Used to preallocate
sl@0: ** storage space.
sl@0: */
sl@0: int sqlite3PcacheSize(void);
sl@0: 
sl@0: /* One release per successful fetch.  Page is pinned until released.
sl@0: ** Reference counted. 
sl@0: */
sl@0: int sqlite3PcacheFetch(PCache*, Pgno, int createFlag, PgHdr**);
sl@0: void sqlite3PcacheRelease(PgHdr*);
sl@0: 
sl@0: void sqlite3PcacheDrop(PgHdr*);         /* Remove page from cache */
sl@0: void sqlite3PcacheMakeDirty(PgHdr*);    /* Make sure page is marked dirty */
sl@0: void sqlite3PcacheMakeClean(PgHdr*);    /* Mark a single page as clean */
sl@0: void sqlite3PcacheCleanAll(PCache*);    /* Mark all dirty list pages as clean */
sl@0: 
sl@0: /* Change a page number.  Used by incr-vacuum. */
sl@0: void sqlite3PcacheMove(PgHdr*, Pgno);
sl@0: 
sl@0: /* Remove all pages with pgno>x.  Reset the cache if x==0 */
sl@0: void sqlite3PcacheTruncate(PCache*, Pgno x);
sl@0: 
sl@0: /* Routines used to implement transactions on memory-only databases. */
sl@0: int sqlite3PcachePreserve(PgHdr*, int);    /* Preserve current page content */
sl@0: void sqlite3PcacheCommit(PCache*, int);    /* Drop preserved copy */
sl@0: void sqlite3PcacheRollback(PCache*, int, void (*xReiniter)(PgHdr*));
sl@0: 
sl@0: /* Get a list of all dirty pages in the cache, sorted by page number */
sl@0: PgHdr *sqlite3PcacheDirtyList(PCache*);
sl@0: 
sl@0: /* Reset and close the cache object */
sl@0: void sqlite3PcacheClose(PCache*);
sl@0: 
sl@0: /* Clear flags from pages of the page cache */
sl@0: void sqlite3PcacheClearFlags(PCache*, int mask);
sl@0: 
sl@0: /* Assert flags settings on all pages.  Debugging only */
sl@0: #ifndef NDEBUG
sl@0:   void sqlite3PcacheAssertFlags(PCache*, int trueMask, int falseMask);
sl@0: #else
sl@0: # define sqlite3PcacheAssertFlags(A,B,C)
sl@0: #endif
sl@0: 
sl@0: /* Return true if the number of dirty pages is 0 or 1 */
sl@0: int sqlite3PcacheZeroOrOneDirtyPages(PCache*);
sl@0: 
sl@0: /* Discard the contents of the cache */
sl@0: int sqlite3PcacheClear(PCache*);
sl@0: 
sl@0: /* Return the total number of outstanding page references */
sl@0: int sqlite3PcacheRefCount(PCache*);
sl@0: 
sl@0: /* Increment the reference count of an existing page */
sl@0: void sqlite3PcacheRef(PgHdr*);
sl@0: 
sl@0: int sqlite3PcachePageRefcount(PgHdr*);
sl@0: 
sl@0: /* Return the total number of pages stored in the cache */
sl@0: int sqlite3PcachePagecount(PCache*);
sl@0: 
sl@0: #ifdef SQLITE_CHECK_PAGES
sl@0: /* Iterate through all pages currently stored in the cache. This interface
sl@0: ** is only available if SQLITE_CHECK_PAGES is defined when the library is 
sl@0: ** built.
sl@0: */
sl@0: void sqlite3PcacheIterate(PCache *pCache, void (*xIter)(PgHdr *));
sl@0: #endif
sl@0: 
sl@0: /* Set and get the suggested cache-size for the specified pager-cache.
sl@0: **
sl@0: ** If no global maximum is configured, then the system attempts to limit
sl@0: ** the total number of pages cached by purgeable pager-caches to the sum
sl@0: ** of the suggested cache-sizes.
sl@0: */
sl@0: int sqlite3PcacheGetCachesize(PCache *);
sl@0: void sqlite3PcacheSetCachesize(PCache *, int);
sl@0: 
sl@0: #ifdef SQLITE_ENABLE_MEMORY_MANAGEMENT
sl@0: /* Try to return memory used by the pcache module to the main memory heap */
sl@0: int sqlite3PcacheReleaseMemory(int);
sl@0: #endif
sl@0: 
sl@0: #ifdef SQLITE_TEST
sl@0: void sqlite3PcacheStats(int*,int*,int*,int*);
sl@0: #endif
sl@0: 
sl@0: #endif /* _PCACHE_H_ */