diff options
Diffstat (limited to 'static/netbsd/man3/sqlite3_pcache_methods2.3')
| -rw-r--r-- | static/netbsd/man3/sqlite3_pcache_methods2.3 | 194 |
1 files changed, 194 insertions, 0 deletions
diff --git a/static/netbsd/man3/sqlite3_pcache_methods2.3 b/static/netbsd/man3/sqlite3_pcache_methods2.3 new file mode 100644 index 00000000..00a09331 --- /dev/null +++ b/static/netbsd/man3/sqlite3_pcache_methods2.3 @@ -0,0 +1,194 @@ +.Dd January 24, 2024 +.Dt SQLITE3_PCACHE_METHODS2 3 +.Os +.Sh NAME +.Nm sqlite3_pcache_methods2 , +.Nm sqlite3_pcache_methods2 +.Nd application defined page cache +.Sh SYNOPSIS +.In sqlite3.h +.Vt typedef struct sqlite3_pcache_methods2 sqlite3_pcache_methods2; +.Vt struct sqlite3_pcache_methods2 ; +.Sh DESCRIPTION +The sqlite3_config(SQLITE_CONFIG_PCACHE2, +\&...) interface can register an alternative page cache implementation +by passing in an instance of the sqlite3_pcache_methods2 structure. +In many applications, most of the heap memory allocated by SQLite is +used for the page cache. +By implementing a custom page cache using this API, an application +can better control the amount of memory consumed by SQLite, the way +in which that memory is allocated and released, and the policies used +to determine exactly which parts of a database file are cached and +for how long. +.Pp +The alternative page cache mechanism is an extreme measure that is +only needed by the most demanding applications. +The built-in page cache is recommended for most uses. +.Pp +The contents of the sqlite3_pcache_methods2 structure are copied to +an internal buffer by SQLite within the call to sqlite3_config. +Hence the application may discard the parameter after the call to +.Fn sqlite3_config +returns. +.Pp +The xInit() method is called once for each effective call to +.Fn sqlite3_initialize +(usually only once during the lifetime of the process). +The xInit() method is passed a copy of the sqlite3_pcache_methods2.pArg +value. +The intent of the xInit() method is to set up global data structures +required by the custom page cache implementation. +If the xInit() method is NULL, then the built-in default page cache +is used instead of the application defined page cache. +.Pp +The xShutdown() method is called by +.Fn sqlite3_shutdown . +It can be used to clean up any outstanding resources before process +shutdown, if required. +The xShutdown() method may be NULL. +.Pp +SQLite automatically serializes calls to the xInit method, so the xInit +method need not be threadsafe. +The xShutdown method is only called from +.Fn sqlite3_shutdown +so it does not need to be threadsafe either. +All other methods must be threadsafe in multithreaded applications. +.Pp +SQLite will never invoke xInit() more than once without an intervening +call to xShutdown(). +.Pp +SQLite invokes the xCreate() method to construct a new cache instance. +SQLite will typically create one cache instance for each open database +file, though this is not guaranteed. +The first parameter, szPage, is the size in bytes of the pages that +must be allocated by the cache. +szPage will always a power of two. +The second parameter szExtra is a number of bytes of extra storage +associated with each page cache entry. +The szExtra parameter will a number less than 250. +SQLite will use the extra szExtra bytes on each page to store metadata +about the underlying database page on disk. +The value passed into szExtra depends on the SQLite version, the target +platform, and how SQLite was compiled. +The third argument to xCreate(), bPurgeable, is true if the cache being +created will be used to cache database pages of a file stored on disk, +or false if it is used for an in-memory database. +The cache implementation does not have to do anything special based +with the value of bPurgeable; it is purely advisory. +On a cache where bPurgeable is false, SQLite will never invoke xUnpin() +except to deliberately delete a page. +In other words, calls to xUnpin() on a cache with bPurgeable set to +false will always have the "discard" flag set to true. +Hence, a cache created with bPurgeable false will never contain any +unpinned pages. +.Pp +The xCachesize() method may be called at any time by SQLite to set +the suggested maximum cache-size (number of pages stored by) the cache +instance passed as the first argument. +This is the value configured using the SQLite "PRAGMA cache_size" +command. +As with the bPurgeable parameter, the implementation is not required +to do anything with this value; it is advisory only. +.Pp +The xPagecount() method must return the number of pages currently stored +in the cache, both pinned and unpinned. +.Pp +The xFetch() method locates a page in the cache and returns a pointer +to an sqlite3_pcache_page object associated with that page, or a NULL +pointer. +The pBuf element of the returned sqlite3_pcache_page object will be +a pointer to a buffer of szPage bytes used to store the content of +a single database page. +The pExtra element of sqlite3_pcache_page will be a pointer to the +szExtra bytes of extra storage that SQLite has requested for each entry +in the page cache. +.Pp +The page to be fetched is determined by the key. +The minimum key value is 1. +After it has been retrieved using xFetch, the page is considered to +be "pinned". +.Pp +If the requested page is already in the page cache, then the page cache +implementation must return a pointer to the page buffer with its content +intact. +If the requested page is not already in the cache, then the cache implementation +should use the value of the createFlag parameter to help it determined +what action to take: +.Pp + createFlag Behavior when page is not already in cache + 0 Do not allocate a new page. +Return NULL. + 1 Allocate a new page if it easy and convenient to do so. +Otherwise return NULL. + 2 Make every effort to allocate a new page. +Only return NULL if allocating a new page is effectively impossible. +.Pp +SQLite will normally invoke xFetch() with a createFlag of 0 or 1. +SQLite will only use a createFlag of 2 after a prior call with a createFlag +of 1 failed. +In between the xFetch() calls, SQLite may attempt to unpin one or more +cache pages by spilling the content of pinned pages to disk and synching +the operating system disk cache. +.Pp +xUnpin() is called by SQLite with a pointer to a currently pinned page +as its second argument. +If the third parameter, discard, is non-zero, then the page must be +evicted from the cache. +If the discard parameter is zero, then the page may be discarded or +retained at the discretion of page cache implementation. +The page cache implementation may choose to evict unpinned pages at +any time. +.Pp +The cache must not perform any reference counting. +A single call to xUnpin() unpins the page regardless of the number +of prior calls to xFetch(). +.Pp +The xRekey() method is used to change the key value associated with +the page passed as the second argument. +If the cache previously contains an entry associated with newKey, it +must be discarded. +Any prior cache entry associated with newKey is guaranteed not to be +pinned. +.Pp +When SQLite calls the xTruncate() method, the cache must discard all +existing cache entries with page numbers (keys) greater than or equal +to the value of the iLimit parameter passed to xTruncate(). +If any of these pages are pinned, they are implicitly unpinned, meaning +that they can be safely discarded. +.Pp +The xDestroy() method is used to delete a cache allocated by xCreate(). +All resources associated with the specified cache should be freed. +After calling the xDestroy() method, SQLite considers the sqlite3_pcache* +handle invalid, and will not use it with any other sqlite3_pcache_methods2 +functions. +.Pp +SQLite invokes the xShrink() method when it wants the page cache to +free up as much of heap memory as possible. +The page cache implementation is not obligated to free any memory, +but well-behaved implementations should do their best. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 8909. +.Bd -literal +typedef struct sqlite3_pcache_methods2 sqlite3_pcache_methods2; +struct sqlite3_pcache_methods2 { + int iVersion; + void *pArg; + int (*xInit)(void*); + void (*xShutdown)(void*); + sqlite3_pcache *(*xCreate)(int szPage, int szExtra, int bPurgeable); + void (*xCachesize)(sqlite3_pcache*, int nCachesize); + int (*xPagecount)(sqlite3_pcache*); + sqlite3_pcache_page *(*xFetch)(sqlite3_pcache*, unsigned key, int createFlag); + void (*xUnpin)(sqlite3_pcache*, sqlite3_pcache_page*, int discard); + void (*xRekey)(sqlite3_pcache*, sqlite3_pcache_page*, + unsigned oldKey, unsigned newKey); + void (*xTruncate)(sqlite3_pcache*, unsigned iLimit); + void (*xDestroy)(sqlite3_pcache*); + void (*xShrink)(sqlite3_pcache*); +}; +.Ed +.Sh SEE ALSO +.Xr sqlite3_config 3 , +.Xr sqlite3_initialize 3 , +.Xr SQLITE_CONFIG_SINGLETHREAD 3 |