1.Dd January 24, 2024 2.Dt SQLITE3_PCACHE_METHODS2 3 3.Os 4.Sh NAME 5.Nm sqlite3_pcache_methods2 , 6.Nm sqlite3_pcache_methods2 7.Nd application defined page cache 8.Sh SYNOPSIS 9.In sqlite3.h 10.Vt typedef struct sqlite3_pcache_methods2 sqlite3_pcache_methods2; 11.Vt struct sqlite3_pcache_methods2 ; 12.Sh DESCRIPTION 13The sqlite3_config(SQLITE_CONFIG_PCACHE2, 14\&...) interface can register an alternative page cache implementation 15by passing in an instance of the sqlite3_pcache_methods2 structure. 16In many applications, most of the heap memory allocated by SQLite is 17used for the page cache. 18By implementing a custom page cache using this API, an application 19can better control the amount of memory consumed by SQLite, the way 20in which that memory is allocated and released, and the policies used 21to determine exactly which parts of a database file are cached and 22for how long. 23.Pp 24The alternative page cache mechanism is an extreme measure that is 25only needed by the most demanding applications. 26The built-in page cache is recommended for most uses. 27.Pp 28The contents of the sqlite3_pcache_methods2 structure are copied to 29an internal buffer by SQLite within the call to sqlite3_config. 30Hence the application may discard the parameter after the call to 31.Fn sqlite3_config 32returns. 33.Pp 34The xInit() method is called once for each effective call to 35.Fn sqlite3_initialize 36(usually only once during the lifetime of the process). 37The xInit() method is passed a copy of the sqlite3_pcache_methods2.pArg 38value. 39The intent of the xInit() method is to set up global data structures 40required by the custom page cache implementation. 41If the xInit() method is NULL, then the built-in default page cache 42is used instead of the application defined page cache. 43.Pp 44The xShutdown() method is called by 45.Fn sqlite3_shutdown . 46It can be used to clean up any outstanding resources before process 47shutdown, if required. 48The xShutdown() method may be NULL. 49.Pp 50SQLite automatically serializes calls to the xInit method, so the xInit 51method need not be threadsafe. 52The xShutdown method is only called from 53.Fn sqlite3_shutdown 54so it does not need to be threadsafe either. 55All other methods must be threadsafe in multithreaded applications. 56.Pp 57SQLite will never invoke xInit() more than once without an intervening 58call to xShutdown(). 59.Pp 60SQLite invokes the xCreate() method to construct a new cache instance. 61SQLite will typically create one cache instance for each open database 62file, though this is not guaranteed. 63The first parameter, szPage, is the size in bytes of the pages that 64must be allocated by the cache. 65szPage will always a power of two. 66The second parameter szExtra is a number of bytes of extra storage 67associated with each page cache entry. 68The szExtra parameter will a number less than 250. 69SQLite will use the extra szExtra bytes on each page to store metadata 70about the underlying database page on disk. 71The value passed into szExtra depends on the SQLite version, the target 72platform, and how SQLite was compiled. 73The third argument to xCreate(), bPurgeable, is true if the cache being 74created will be used to cache database pages of a file stored on disk, 75or false if it is used for an in-memory database. 76The cache implementation does not have to do anything special based 77with the value of bPurgeable; it is purely advisory. 78On a cache where bPurgeable is false, SQLite will never invoke xUnpin() 79except to deliberately delete a page. 80In other words, calls to xUnpin() on a cache with bPurgeable set to 81false will always have the "discard" flag set to true. 82Hence, a cache created with bPurgeable false will never contain any 83unpinned pages. 84.Pp 85The xCachesize() method may be called at any time by SQLite to set 86the suggested maximum cache-size (number of pages stored by) the cache 87instance passed as the first argument. 88This is the value configured using the SQLite "PRAGMA cache_size" 89command. 90As with the bPurgeable parameter, the implementation is not required 91to do anything with this value; it is advisory only. 92.Pp 93The xPagecount() method must return the number of pages currently stored 94in the cache, both pinned and unpinned. 95.Pp 96The xFetch() method locates a page in the cache and returns a pointer 97to an sqlite3_pcache_page object associated with that page, or a NULL 98pointer. 99The pBuf element of the returned sqlite3_pcache_page object will be 100a pointer to a buffer of szPage bytes used to store the content of 101a single database page. 102The pExtra element of sqlite3_pcache_page will be a pointer to the 103szExtra bytes of extra storage that SQLite has requested for each entry 104in the page cache. 105.Pp 106The page to be fetched is determined by the key. 107The minimum key value is 1. 108After it has been retrieved using xFetch, the page is considered to 109be "pinned". 110.Pp 111If the requested page is already in the page cache, then the page cache 112implementation must return a pointer to the page buffer with its content 113intact. 114If the requested page is not already in the cache, then the cache implementation 115should use the value of the createFlag parameter to help it determined 116what action to take: 117.Pp 118 createFlag Behavior when page is not already in cache 119 0 Do not allocate a new page. 120Return NULL. 121 1 Allocate a new page if it easy and convenient to do so. 122Otherwise return NULL. 123 2 Make every effort to allocate a new page. 124Only return NULL if allocating a new page is effectively impossible. 125.Pp 126SQLite will normally invoke xFetch() with a createFlag of 0 or 1. 127SQLite will only use a createFlag of 2 after a prior call with a createFlag 128of 1 failed. 129In between the xFetch() calls, SQLite may attempt to unpin one or more 130cache pages by spilling the content of pinned pages to disk and synching 131the operating system disk cache. 132.Pp 133xUnpin() is called by SQLite with a pointer to a currently pinned page 134as its second argument. 135If the third parameter, discard, is non-zero, then the page must be 136evicted from the cache. 137If the discard parameter is zero, then the page may be discarded or 138retained at the discretion of page cache implementation. 139The page cache implementation may choose to evict unpinned pages at 140any time. 141.Pp 142The cache must not perform any reference counting. 143A single call to xUnpin() unpins the page regardless of the number 144of prior calls to xFetch(). 145.Pp 146The xRekey() method is used to change the key value associated with 147the page passed as the second argument. 148If the cache previously contains an entry associated with newKey, it 149must be discarded. 150Any prior cache entry associated with newKey is guaranteed not to be 151pinned. 152.Pp 153When SQLite calls the xTruncate() method, the cache must discard all 154existing cache entries with page numbers (keys) greater than or equal 155to the value of the iLimit parameter passed to xTruncate(). 156If any of these pages are pinned, they are implicitly unpinned, meaning 157that they can be safely discarded. 158.Pp 159The xDestroy() method is used to delete a cache allocated by xCreate(). 160All resources associated with the specified cache should be freed. 161After calling the xDestroy() method, SQLite considers the sqlite3_pcache* 162handle invalid, and will not use it with any other sqlite3_pcache_methods2 163functions. 164.Pp 165SQLite invokes the xShrink() method when it wants the page cache to 166free up as much of heap memory as possible. 167The page cache implementation is not obligated to free any memory, 168but well-behaved implementations should do their best. 169.Sh IMPLEMENTATION NOTES 170These declarations were extracted from the 171interface documentation at line 8909. 172.Bd -literal 173typedef struct sqlite3_pcache_methods2 sqlite3_pcache_methods2; 174struct sqlite3_pcache_methods2 { 175 int iVersion; 176 void *pArg; 177 int (*xInit)(void*); 178 void (*xShutdown)(void*); 179 sqlite3_pcache *(*xCreate)(int szPage, int szExtra, int bPurgeable); 180 void (*xCachesize)(sqlite3_pcache*, int nCachesize); 181 int (*xPagecount)(sqlite3_pcache*); 182 sqlite3_pcache_page *(*xFetch)(sqlite3_pcache*, unsigned key, int createFlag); 183 void (*xUnpin)(sqlite3_pcache*, sqlite3_pcache_page*, int discard); 184 void (*xRekey)(sqlite3_pcache*, sqlite3_pcache_page*, 185 unsigned oldKey, unsigned newKey); 186 void (*xTruncate)(sqlite3_pcache*, unsigned iLimit); 187 void (*xDestroy)(sqlite3_pcache*); 188 void (*xShrink)(sqlite3_pcache*); 189}; 190.Ed 191.Sh SEE ALSO 192.Xr sqlite3_config 3 , 193.Xr sqlite3_initialize 3 , 194.Xr SQLITE_CONFIG_SINGLETHREAD 3 195