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