blob: 8c44287b36ac75b50fd989c2a232414022cf8905 [file] [log] [blame]
danielk19778c0a7912008-08-20 14:49:23 +00001/*
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**
danielk1977f3d3c272008-11-19 16:52:44 +000015** @(#) $Id: pcache.h,v 1.16 2008/11/19 16:52:44 danielk1977 Exp $
danielk19778c0a7912008-08-20 14:49:23 +000016*/
17
18#ifndef _PCACHE_H_
19
20typedef struct PgHdr PgHdr;
21typedef struct PCache PCache;
22
23/*
24** Every page in the cache is controlled by an instance of the following
25** structure.
26*/
27struct PgHdr {
danielk19778c0a7912008-08-20 14:49:23 +000028 void *pData; /* Content of this page */
29 void *pExtra; /* Extra content */
30 PgHdr *pDirty; /* Transient list of dirty pages */
31 Pgno pgno; /* Page number for this page */
drha85f7e32008-08-28 02:26:07 +000032 Pager *pPager; /* The pager this page is part of */
danielk19778c0a7912008-08-20 14:49:23 +000033#ifdef SQLITE_CHECK_PAGES
drha85f7e32008-08-28 02:26:07 +000034 u32 pageHash; /* Hash of page content */
danielk19778c0a7912008-08-20 14:49:23 +000035#endif
drha85f7e32008-08-28 02:26:07 +000036 u16 flags; /* PGHDR flags defined below */
danielk1977bc2ca9e2008-11-13 14:28:28 +000037
drha85f7e32008-08-28 02:26:07 +000038 /**********************************************************************
39 ** Elements above are public. All that follows is private to pcache.c
40 ** and should not be accessed by other modules.
41 */
42 i16 nRef; /* Number of users of this page */
danielk19778c0a7912008-08-20 14:49:23 +000043 PCache *pCache; /* Cache that owns this page */
danielk1977b3175382008-10-17 18:51:52 +000044
danielk1977bc2ca9e2008-11-13 14:28:28 +000045 PgHdr *pDirtyNext; /* Next element in list of dirty pages */
46 PgHdr *pDirtyPrev; /* Previous element in list of dirty pages */
danielk19778c0a7912008-08-20 14:49:23 +000047};
48
49/* Bit values for PgHdr.flags */
drhb3df2e12008-09-17 20:06:26 +000050#define PGHDR_DIRTY 0x002 /* Page has changed */
51#define PGHDR_NEED_SYNC 0x004 /* Fsync the rollback journal before
52 ** writing this page to the database */
53#define PGHDR_NEED_READ 0x008 /* Content is unread */
54#define PGHDR_REUSE_UNLIKELY 0x010 /* A hint that reuse is unlikely */
55#define PGHDR_DONT_WRITE 0x020 /* Do not write content to disk */
danielk19778c0a7912008-08-20 14:49:23 +000056
57/* Initialize and shutdown the page cache subsystem */
58int sqlite3PcacheInitialize(void);
59void sqlite3PcacheShutdown(void);
60
61/* Page cache buffer management:
62** These routines implement SQLITE_CONFIG_PAGECACHE.
63*/
64void sqlite3PCacheBufferSetup(void *, int sz, int n);
danielk19778c0a7912008-08-20 14:49:23 +000065
66/* Create a new pager cache.
67** Under memory stress, invoke xStress to try to make pages clean.
68** Only clean and unpinned pages can be reclaimed.
69*/
70void sqlite3PcacheOpen(
danielk1977a858aa22008-08-22 16:22:17 +000071 int szPage, /* Size of every page */
72 int szExtra, /* Extra space associated with each page */
73 int bPurgeable, /* True if pages are on backing store */
danielk1977a858aa22008-08-22 16:22:17 +000074 int (*xStress)(void*, PgHdr*), /* Call to try to make pages clean */
75 void *pStress, /* Argument to xStress */
76 PCache *pToInit /* Preallocated space for the PCache */
danielk19778c0a7912008-08-20 14:49:23 +000077);
78
79/* Modify the page-size after the cache has been created. */
80void sqlite3PcacheSetPageSize(PCache *, int);
81
82/* Return the size in bytes of a PCache object. Used to preallocate
83** storage space.
84*/
85int sqlite3PcacheSize(void);
86
87/* One release per successful fetch. Page is pinned until released.
88** Reference counted.
89*/
90int sqlite3PcacheFetch(PCache*, Pgno, int createFlag, PgHdr**);
91void sqlite3PcacheRelease(PgHdr*);
92
93void sqlite3PcacheDrop(PgHdr*); /* Remove page from cache */
94void sqlite3PcacheMakeDirty(PgHdr*); /* Make sure page is marked dirty */
95void sqlite3PcacheMakeClean(PgHdr*); /* Mark a single page as clean */
96void sqlite3PcacheCleanAll(PCache*); /* Mark all dirty list pages as clean */
97
98/* Change a page number. Used by incr-vacuum. */
99void sqlite3PcacheMove(PgHdr*, Pgno);
100
danielk19778c0a7912008-08-20 14:49:23 +0000101/* Remove all pages with pgno>x. Reset the cache if x==0 */
102void sqlite3PcacheTruncate(PCache*, Pgno x);
103
danielk19778c0a7912008-08-20 14:49:23 +0000104/* Get a list of all dirty pages in the cache, sorted by page number */
105PgHdr *sqlite3PcacheDirtyList(PCache*);
106
danielk19778c0a7912008-08-20 14:49:23 +0000107/* Reset and close the cache object */
108void sqlite3PcacheClose(PCache*);
109
drhb3df2e12008-09-17 20:06:26 +0000110/* Clear flags from pages of the page cache */
danielk1977bc2ca9e2008-11-13 14:28:28 +0000111void sqlite3PcacheClearSyncFlags(PCache *);
danielk19778c0a7912008-08-20 14:49:23 +0000112
danielk19778c0a7912008-08-20 14:49:23 +0000113/* Discard the contents of the cache */
114int sqlite3PcacheClear(PCache*);
115
116/* Return the total number of outstanding page references */
117int sqlite3PcacheRefCount(PCache*);
118
119/* Increment the reference count of an existing page */
120void sqlite3PcacheRef(PgHdr*);
121
danielk197771d5d2c2008-09-29 11:49:47 +0000122int sqlite3PcachePageRefcount(PgHdr*);
123
danielk19778c0a7912008-08-20 14:49:23 +0000124/* Return the total number of pages stored in the cache */
125int sqlite3PcachePagecount(PCache*);
126
drh419fcf62008-10-11 17:42:28 +0000127#ifdef SQLITE_CHECK_PAGES
danielk1977bc2ca9e2008-11-13 14:28:28 +0000128/* Iterate through all dirty pages currently stored in the cache. This
129** interface is only available if SQLITE_CHECK_PAGES is defined when the
130** library is built.
danielk19778c0a7912008-08-20 14:49:23 +0000131*/
danielk1977bc2ca9e2008-11-13 14:28:28 +0000132void sqlite3PcacheIterateDirty(PCache *pCache, void (*xIter)(PgHdr *));
drh419fcf62008-10-11 17:42:28 +0000133#endif
danielk19778c0a7912008-08-20 14:49:23 +0000134
danielk1977d491e1b2008-08-26 18:05:48 +0000135/* Set and get the suggested cache-size for the specified pager-cache.
danielk19778c0a7912008-08-20 14:49:23 +0000136**
137** If no global maximum is configured, then the system attempts to limit
138** the total number of pages cached by purgeable pager-caches to the sum
139** of the suggested cache-sizes.
140*/
danielk19778c0a7912008-08-20 14:49:23 +0000141void sqlite3PcacheSetCachesize(PCache *, int);
danielk1977f3d3c272008-11-19 16:52:44 +0000142#ifdef SQLITE_TEST
143int sqlite3PcacheGetCachesize(PCache *);
144#endif
danielk19778c0a7912008-08-20 14:49:23 +0000145
drh419fcf62008-10-11 17:42:28 +0000146#ifdef SQLITE_ENABLE_MEMORY_MANAGEMENT
danielk1977d491e1b2008-08-26 18:05:48 +0000147/* Try to return memory used by the pcache module to the main memory heap */
danielk197767e3da72008-08-21 12:19:44 +0000148int sqlite3PcacheReleaseMemory(int);
drh419fcf62008-10-11 17:42:28 +0000149#endif
danielk197767e3da72008-08-21 12:19:44 +0000150
drh419fcf62008-10-11 17:42:28 +0000151#ifdef SQLITE_TEST
danielk1977062d4cb2008-08-29 09:10:02 +0000152void sqlite3PcacheStats(int*,int*,int*,int*);
drh419fcf62008-10-11 17:42:28 +0000153#endif
danielk1977062d4cb2008-08-29 09:10:02 +0000154
danielk1977bc2ca9e2008-11-13 14:28:28 +0000155void sqlite3PCacheSetDefault(void);
156
danielk19778c0a7912008-08-20 14:49:23 +0000157#endif /* _PCACHE_H_ */