Adding upstream version 3.45.1.upstream/3.45.1

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
author: Daniel Baumann <daniel.baumann@progress-linux.org> 2024-04-13 14:07:11 +0000
committer: Daniel Baumann <daniel.baumann@progress-linux.org> 2024-04-13 14:07:11 +0000
commit: 63847496f14c813a5d80efd5b7de0f1294ffe1e3 (patch)
tree: 01c7571c7c762ceee70638549a99834fdd7c411b /www/c3ref/pcache_methods2.html
parent: Initial commit. (diff)
download: sqlite3-63847496f14c813a5d80efd5b7de0f1294ffe1e3.tar.xz
sqlite3-63847496f14c813a5d80efd5b7de0f1294ffe1e3.zip
1 files changed, 311 insertions, 0 deletions
diff --git a/www/c3ref/pcache_methods2.html b/www/c3ref/pcache_methods2.html
new file mode 100644
index 0000000..d4d7b98
--- /dev/null
+++ b/www/c3ref/pcache_methods2.html
@@ -0,0 +1,311 @@
+<!DOCTYPE html>
+<html><head>
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<meta http-equiv="content-type" content="text/html; charset=UTF-8">
+<link href="../sqlite.css" rel="stylesheet">
+<title>Application Defined Page Cache.</title>
+<!-- path=../ -->
+</head>
+<body>
+<div class=nosearch>
+<a href="../index.html">
+<img class="logo" src="../images/sqlite370_banner.gif" alt="SQLite" border="0">
+</a>
+<div><!-- IE hack to prevent disappearing logo --></div>
+<div class="tagline desktoponly">
+Small. Fast. Reliable.<br>Choose any three.
+</div>
+<div class="menu mainmenu">
+<ul>
+<li><a href="../index.html">Home</a>
+<li class='mobileonly'><a href="javascript:void(0)" onclick='toggle_div("submenu")'>Menu</a>
+<li class='wideonly'><a href='../about.html'>About</a>
+<li class='desktoponly'><a href="../docs.html">Documentation</a>
+<li class='desktoponly'><a href="../download.html">Download</a>
+<li class='wideonly'><a href='../copyright.html'>License</a>
+<li class='desktoponly'><a href="../support.html">Support</a>
+<li class='desktoponly'><a href="../prosupport.html">Purchase</a>
+<li class='search' id='search_menubutton'>
+<a href="javascript:void(0)" onclick='toggle_search()'>Search</a>
+</ul>
+</div>
+<div class="menu submenu" id="submenu">
+<ul>
+<li><a href='../about.html'>About</a>
+<li><a href='../docs.html'>Documentation</a>
+<li><a href='../download.html'>Download</a>
+<li><a href='../support.html'>Support</a>
+<li><a href='../prosupport.html'>Purchase</a>
+</ul>
+</div>
+<div class="searchmenu" id="searchmenu">
+<form method="GET" action="../search">
+<select name="s" id="searchtype">
+<option value="d">Search Documentation</option>
+<option value="c">Search Changelog</option>
+</select>
+<input type="text" name="q" id="searchbox" value="">
+<input type="submit" value="Go">
+</form>
+</div>
+</div>
+<script>
+function toggle_div(nm) {
+var w = document.getElementById(nm);
+if( w.style.display=="block" ){
+w.style.display = "none";
+}else{
+w.style.display = "block";
+}
+}
+function toggle_search() {
+var w = document.getElementById("searchmenu");
+if( w.style.display=="block" ){
+w.style.display = "none";
+} else {
+w.style.display = "block";
+setTimeout(function(){
+document.getElementById("searchbox").focus()
+}, 30);
+}
+}
+function div_off(nm){document.getElementById(nm).style.display="none";}
+window.onbeforeunload = function(e){div_off("submenu");}
+/* Disable the Search feature if we are not operating from CGI, since */
+/* Search is accomplished using CGI and will not work without it. */
+if( !location.origin || !location.origin.match || !location.origin.match(/http/) ){
+document.getElementById("search_menubutton").style.display = "none";
+}
+/* Used by the Hide/Show button beside syntax diagrams, to toggle the */
+function hideorshow(btn,obj){
+var x = document.getElementById(obj);
+var b = document.getElementById(btn);
+if( x.style.display!='none' ){
+x.style.display = 'none';
+b.innerHTML='show';
+}else{
+x.style.display = '';
+b.innerHTML='hide';
+}
+return false;
+}
+var antiRobot = 0;
+function antiRobotGo(){
+if( antiRobot!=3 ) return;
+antiRobot = 7;
+var j = document.getElementById("mtimelink");
+if(j && j.hasAttribute("data-href")) j.href=j.getAttribute("data-href");
+}
+function antiRobotDefense(){
+document.body.onmousedown=function(){
+antiRobot |= 2;
+antiRobotGo();
+document.body.onmousedown=null;
+}
+document.body.onmousemove=function(){
+antiRobot |= 2;
+antiRobotGo();
+document.body.onmousemove=null;
+}
+setTimeout(function(){
+antiRobot |= 1;
+antiRobotGo();
+}, 100)
+antiRobotGo();
+}
+antiRobotDefense();
+</script>
+<!-- keywords: {page cache} sqlite3_pcache_methods2 -->
+<div class=nosearch>
+<a href="../c3ref/intro.html"><h2>SQLite C Interface</h2></a>
+<h2>Application Defined Page Cache.</h2>
+</div>
+<blockquote><pre>
+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*);
+};
+</pre></blockquote>
+<p>
+The <a href="../c3ref/config.html">sqlite3_config</a>(<a href="../c3ref/c_config_covering_index_scan.html#sqliteconfigpcache2">SQLITE_CONFIG_PCACHE2</a>, ...) 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.</p>
+
+<p>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.</p>
+
+<p>The contents of the sqlite3_pcache_methods2 structure are copied to an
+internal buffer by SQLite within the call to <a href="../c3ref/config.html">sqlite3_config</a>.  Hence
+the application may discard the parameter after the call to
+<a href="../c3ref/config.html">sqlite3_config()</a> returns.</p>
+
+<p><a name="thexinitpagecachemethod"></a>
+
+The xInit() method is called once for each effective
+call to <a href="../c3ref/initialize.html">sqlite3_initialize()</a>
+(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.</p>
+
+<p><a name="thexshutdownpagecachemethod"></a>
+
+The xShutdown() method is called by <a href="../c3ref/initialize.html">sqlite3_shutdown()</a>.
+It can be used to clean up
+any outstanding resources before process shutdown, if required.
+The xShutdown() method may be NULL.</p>
+
+<p>SQLite automatically serializes calls to the xInit method,
+so the xInit method need not be threadsafe.  The
+xShutdown method is only called from <a href="../c3ref/initialize.html">sqlite3_shutdown()</a> so it does
+not need to be threadsafe either.  All other methods must be threadsafe
+in multithreaded applications.</p>
+
+<p>SQLite will never invoke xInit() more than once without an intervening
+call to xShutdown().</p>
+
+<p><a name="thexcreatepagecachemethods"></a>
+
+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.</p>
+
+<p><a name="thexcachesizepagecachemethod"></a>
+
+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 "<a href="../pragma.html#pragma_cache_size">PRAGMA cache_size</a>" command.  As with the bPurgeable
+parameter, the implementation is not required to do anything with this
+value; it is advisory only.</p>
+
+<p><a name="thexpagecountpagecachemethods"></a>
+
+The xPagecount() method must return the number of pages currently
+stored in the cache, both pinned and unpinned.</p>
+
+<p><a name="thexfetchpagecachemethods"></a>
+
+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.</p>
+
+<p>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".</p>
+
+<p>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:</p>
+
+<p><table border=1 width=85% align=center>
+<tr><th> createFlag <th> Behavior when page is not already in cache
+<tr><td> 0 <td> Do not allocate a new page.  Return NULL.
+<tr><td> 1 <td> Allocate a new page if it easy and convenient to do so.
+Otherwise return NULL.
+<tr><td> 2 <td> Make every effort to allocate a new page.  Only return
+NULL if allocating a new page is effectively impossible.
+</table></p>
+
+<p>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.</p>
+
+<p><a name="thexunpinpagecachemethod"></a>
+
+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.</p>
+
+<p>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().</p>
+
+<p><a name="thexrekeypagecachemethods"></a>
+
+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.</p>
+
+<p>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.</p>
+
+<p><a name="thexdestroypagecachemethod"></a>
+
+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 <a href="../c3ref/pcache.html">sqlite3_pcache*</a>
+handle invalid, and will not use it with any other sqlite3_pcache_methods2
+functions.</p>
+
+<p><a name="thexshrinkpagecachemethod"></a>
+
+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.
+</p><p>See also lists of
+  <a href="../c3ref/objlist.html">Objects</a>,
+  <a href="../c3ref/constlist.html">Constants</a>, and
+  <a href="../c3ref/funclist.html">Functions</a>.</p>
+
author	Daniel Baumann <daniel.baumann@progress-linux.org>	2024-04-13 14:07:11 +0000
committer	Daniel Baumann <daniel.baumann@progress-linux.org>	2024-04-13 14:07:11 +0000
commit	63847496f14c813a5d80efd5b7de0f1294ffe1e3 (patch)
tree	01c7571c7c762ceee70638549a99834fdd7c411b /www/c3ref/pcache_methods2.html
parent	Initial commit. (diff)
download	sqlite3-63847496f14c813a5d80efd5b7de0f1294ffe1e3.tar.xz sqlite3-63847496f14c813a5d80efd5b7de0f1294ffe1e3.zip