Debian Codegraph @

www/c3ref/pcache_methods2.html

raw
1 <!DOCTYPE html>
2 <html><head>
3 <meta name="viewport" content="width=device-width, initial-scale=1.0">
4 <meta http-equiv="content-type" content="text/html; charset=UTF-8">
5 <link href="../sqlite.css" rel="stylesheet">
6 <title>Application Defined Page Cache.</title>
7 <!-- path=../ -->
8 </head>
9 <body>
10 <div class=nosearch>
11 <a href="../index.html">
12 <img class="logo" src="../images/sqlite370_banner.svg" alt="SQLite" border="0">
13 </a>
14 <div><!-- IE hack to prevent disappearing logo --></div>
15 <div class="tagline desktoponly">
16 Small. Fast. Reliable.<br>Choose any three.
17 </div>
18 <div class="menu mainmenu">
19 <ul>
20 <li><a href="../index.html">Home</a>
21 <li class='mobileonly'><a href="javascript:void(0)" onclick='toggle_div("submenu")'>Menu</a>
22 <li class='wideonly'><a href='../about.html'>About</a>
23 <li class='desktoponly'><a href="../docs.html">Documentation</a>
24 <li class='desktoponly'><a href="../download.html">Download</a>
25 <li class='wideonly'><a href='../copyright.html'>License</a>
26 <li class='desktoponly'><a href="../support.html">Support</a>
27 <li class='desktoponly'><a href="../prosupport.html">Purchase</a>
28 <li class='search' id='search_menubutton'>
29 <a href="javascript:void(0)" onclick='toggle_search()'>Search</a>
30 </ul>
31 </div>
32 <div class="menu submenu" id="submenu">
33 <ul>
34 <li><a href='../about.html'>About</a>
35 <li><a href='../docs.html'>Documentation</a>
36 <li><a href='../download.html'>Download</a>
37 <li><a href='../support.html'>Support</a>
38 <li><a href='../prosupport.html'>Purchase</a>
39 </ul>
40 </div>
41 <div class="searchmenu" id="searchmenu">
42 <form method="GET" action="../search">
43 <select name="s" id="searchtype">
44 <option value="d">Search Documentation</option>
45 <option value="c">Search Changelog</option>
46 </select>
47 <input type="text" name="q" id="searchbox" value="">
48 <input type="submit" value="Go">
49 </form>
50 </div>
51 </div>
52 <script>
53 function toggle_div(nm) {
54 var w = document.getElementById(nm);
55 if( w.style.display=="block" ){
56 w.style.display = "none";
57 }else{
58 w.style.display = "block";
59 }
60 }
61 function toggle_search() {
62 var w = document.getElementById("searchmenu");
63 if( w.style.display=="block" ){
64 w.style.display = "none";
65 } else {
66 w.style.display = "block";
67 setTimeout(function(){
68 document.getElementById("searchbox").focus()
69 }, 30);
70 }
71 }
72 function div_off(nm){document.getElementById(nm).style.display="none";}
73 window.onbeforeunload = function(e){div_off("submenu");}
74 /* Disable the Search feature if we are not operating from CGI, since */
75 /* Search is accomplished using CGI and will not work without it. */
76 if( !location.origin || !location.origin.match || !location.origin.match(/http/) ){
77 document.getElementById("search_menubutton").style.display = "none";
78 }
79 /* Used by the Hide/Show button beside syntax diagrams, to toggle the */
80 function hideorshow(btn,obj){
81 var x = document.getElementById(obj);
82 var b = document.getElementById(btn);
83 if( x.style.display!='none' ){
84 x.style.display = 'none';
85 b.innerHTML='show';
86 }else{
87 x.style.display = '';
88 b.innerHTML='hide';
89 }
90 return false;
91 }
92 var antiRobot = 0;
93 function antiRobotGo(){
94 if( antiRobot!=3 ) return;
95 antiRobot = 7;
96 var j = document.getElementById("mtimelink");
97 if(j && j.hasAttribute("data-href")) j.href=j.getAttribute("data-href");
98 }
99 function antiRobotDefense(){
100 document.body.onmousedown=function(){
101 antiRobot |= 2;
102 antiRobotGo();
103 document.body.onmousedown=null;
104 }
105 document.body.onmousemove=function(){
106 antiRobot |= 2;
107 antiRobotGo();
108 document.body.onmousemove=null;
109 }
110 setTimeout(function(){
111 antiRobot |= 1;
112 antiRobotGo();
113 }, 100)
114 antiRobotGo();
115 }
116 antiRobotDefense();
117 </script>
118 <!-- keywords: {page cache} sqlite3_pcache_methods2 -->
119 <div class=nosearch>
120 <a href="../c3ref/intro.html"><h2>SQLite C Interface</h2></a>
121 <h2>Application Defined Page Cache.</h2>
122 </div>
123 <blockquote><pre>
124 typedef struct sqlite3_pcache_methods2 sqlite3_pcache_methods2;
125 struct sqlite3_pcache_methods2 {
126 int iVersion;
127 void *pArg;
128 int (*xInit)(void*);
129 void (*xShutdown)(void*);
130 sqlite3_pcache *(*xCreate)(int szPage, int szExtra, int bPurgeable);
131 void (*xCachesize)(sqlite3_pcache*, int nCachesize);
132 int (*xPagecount)(sqlite3_pcache*);
133 sqlite3_pcache_page *(*xFetch)(sqlite3_pcache*, unsigned key, int createFlag);
134 void (*xUnpin)(sqlite3_pcache*, sqlite3_pcache_page*, int discard);
135 void (*xRekey)(sqlite3_pcache*, sqlite3_pcache_page*,
136 unsigned oldKey, unsigned newKey);
137 void (*xTruncate)(sqlite3_pcache*, unsigned iLimit);
138 void (*xDestroy)(sqlite3_pcache*);
139 void (*xShrink)(sqlite3_pcache*);
140 };
141 </pre></blockquote>
142 <p>
143 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
144 register an alternative page cache implementation by passing in an
145 instance of the sqlite3_pcache_methods2 structure.
146 In many applications, most of the heap memory allocated by
147 SQLite is used for the page cache.
148 By implementing a
149 custom page cache using this API, an application can better control
150 the amount of memory consumed by SQLite, the way in which
151 that memory is allocated and released, and the policies used to
152 determine exactly which parts of a database file are cached and for
153 how long.</p>
154
155 <p>The alternative page cache mechanism is an
156 extreme measure that is only needed by the most demanding applications.
157 The built-in page cache is recommended for most uses.</p>
158
159 <p>The contents of the sqlite3_pcache_methods2 structure are copied to an
160 internal buffer by SQLite within the call to <a href="../c3ref/config.html">sqlite3_config</a>. Hence
161 the application may discard the parameter after the call to
162 <a href="../c3ref/config.html">sqlite3_config()</a> returns.</p>
163
164 <p><a name="thexinitpagecachemethod"></a>
165
166 The xInit() method is called once for each effective
167 call to <a href="../c3ref/initialize.html">sqlite3_initialize()</a>
168 (usually only once during the lifetime of the process). The xInit()
169 method is passed a copy of the sqlite3_pcache_methods2.pArg value.
170 The intent of the xInit() method is to set up global data structures
171 required by the custom page cache implementation.
172 If the xInit() method is NULL, then the
173 built-in default page cache is used instead of the application defined
174 page cache.</p>
175
176 <p><a name="thexshutdownpagecachemethod"></a>
177
178 The xShutdown() method is called by <a href="../c3ref/initialize.html">sqlite3_shutdown()</a>.
179 It can be used to clean up
180 any outstanding resources before process shutdown, if required.
181 The xShutdown() method may be NULL.</p>
182
183 <p>SQLite automatically serializes calls to the xInit method,
184 so the xInit method need not be threadsafe. The
185 xShutdown method is only called from <a href="../c3ref/initialize.html">sqlite3_shutdown()</a> so it does
186 not need to be threadsafe either. All other methods must be threadsafe
187 in multithreaded applications.</p>
188
189 <p>SQLite will never invoke xInit() more than once without an intervening
190 call to xShutdown().</p>
191
192 <p><a name="thexcreatepagecachemethods"></a>
193
194 SQLite invokes the xCreate() method to construct a new cache instance.
195 SQLite will typically create one cache instance for each open database file,
196 though this is not guaranteed. The
197 first parameter, szPage, is the size in bytes of the pages that must
198 be allocated by the cache. szPage will always be a power of two. The
199 second parameter szExtra is a number of bytes of extra storage
200 associated with each page cache entry. The szExtra parameter will be
201 a number less than 250. SQLite will use the
202 extra szExtra bytes on each page to store metadata about the underlying
203 database page on disk. The value passed into szExtra depends
204 on the SQLite version, the target platform, and how SQLite was compiled.
205 The third argument to xCreate(), bPurgeable, is true if the cache being
206 created will be used to cache database pages of a file stored on disk, or
207 false if it is used for an in-memory database. The cache implementation
208 does not have to do anything special based upon the value of bPurgeable;
209 it is purely advisory. On a cache where bPurgeable is false, SQLite will
210 never invoke xUnpin() except to deliberately delete a page.
211 In other words, calls to xUnpin() on a cache with bPurgeable set to
212 false will always have the "discard" flag set to true.
213 Hence, a cache created with bPurgeable set to false will
214 never contain any unpinned pages.</p>
215
216 <p><a name="thexcachesizepagecachemethod"></a>
217
218 The xCachesize() method may be called at any time by SQLite to set the
219 suggested maximum cache-size (number of pages stored) for the cache
220 instance passed as the first argument. This is the value configured using
221 the SQLite "<a href="../pragma.html#pragma_cache_size">PRAGMA cache_size</a>" command. As with the bPurgeable
222 parameter, the implementation is not required to do anything with this
223 value; it is advisory only.</p>
224
225 <p><a name="thexpagecountpagecachemethods"></a>
226
227 The xPagecount() method must return the number of pages currently
228 stored in the cache, both pinned and unpinned.</p>
229
230 <p><a name="thexfetchpagecachemethods"></a>
231
232 The xFetch() method locates a page in the cache and returns a pointer to
233 an sqlite3_pcache_page object associated with that page, or a NULL pointer.
234 The pBuf element of the returned sqlite3_pcache_page object will be a
235 pointer to a buffer of szPage bytes used to store the content of a
236 single database page. The pExtra element of sqlite3_pcache_page will be
237 a pointer to the szExtra bytes of extra storage that SQLite has requested
238 for each entry in the page cache.</p>
239
240 <p>The page to be fetched is determined by the key. The minimum key value
241 is 1. After it has been retrieved using xFetch, the page is considered
242 to be "pinned".</p>
243
244 <p>If the requested page is already in the page cache, then the page cache
245 implementation must return a pointer to the page buffer with its content
246 intact. If the requested page is not already in the cache, then the
247 cache implementation should use the value of the createFlag
248 parameter to help it determine what action to take:</p>
249
250 <p><table border=1 width=85% align=center>
251 <tr><th> createFlag <th> Behavior when page is not already in cache
252 <tr><td> 0 <td> Do not allocate a new page. Return NULL.
253 <tr><td> 1 <td> Allocate a new page if it is easy and convenient to do so.
254 Otherwise return NULL.
255 <tr><td> 2 <td> Make every effort to allocate a new page. Only return
256 NULL if allocating a new page is effectively impossible.
257 </table></p>
258
259 <p>SQLite will normally invoke xFetch() with a createFlag of 0 or 1. SQLite
260 will only use a createFlag of 2 after a prior call with a createFlag of 1
261 failed. In between the xFetch() calls, SQLite may
262 attempt to unpin one or more cache pages by spilling the content of
263 pinned pages to disk and synching the operating system disk cache.</p>
264
265 <p><a name="thexunpinpagecachemethod"></a>
266
267 xUnpin() is called by SQLite with a pointer to a currently pinned page
268 as its second argument. If the third parameter, discard, is non-zero,
269 then the page must be evicted from the cache.
270 If the discard parameter is
271 zero, then the page may be discarded or retained at the discretion of the
272 page cache implementation. The page cache implementation
273 may choose to evict unpinned pages at any time.</p>
274
275 <p>The cache must not perform any reference counting. A single
276 call to xUnpin() unpins the page regardless of the number of prior calls
277 to xFetch().</p>
278
279 <p><a name="thexrekeypagecachemethods"></a>
280
281 The xRekey() method is used to change the key value associated with the
282 page passed as the second argument. If the cache
283 previously contains an entry associated with newKey, it must be
284 discarded. Any prior cache entry associated with newKey is guaranteed not
285 to be pinned.</p>
286
287 <p>When SQLite calls the xTruncate() method, the cache must discard all
288 existing cache entries with page numbers (keys) greater than or equal
289 to the value of the iLimit parameter passed to xTruncate(). If any
290 of these pages are pinned, they become implicitly unpinned, meaning that
291 they can be safely discarded.</p>
292
293 <p><a name="thexdestroypagecachemethod"></a>
294
295 The xDestroy() method is used to delete a cache allocated by xCreate().
296 All resources associated with the specified cache should be freed. After
297 calling the xDestroy() method, SQLite considers the <a href="../c3ref/pcache.html">sqlite3_pcache*</a>
298 handle invalid, and will not use it with any other sqlite3_pcache_methods2
299 functions.</p>
300
301 <p><a name="thexshrinkpagecachemethod"></a>
302
303 SQLite invokes the xShrink() method when it wants the page cache to
304 free up as much of heap memory as possible. The page cache implementation
305 is not obligated to free any memory, but well-behaved implementations should
306 do their best.
307 </p><p>See also lists of
308 <a href="../c3ref/objlist.html">Objects</a>,
309 <a href="../c3ref/constlist.html">Constants</a>, and
310 <a href="../c3ref/funclist.html">Functions</a>.</p>
311