📄 pcache_methods.html

📁 sqlite3源码,适合作为嵌入式（embedded）
💻 HTML
字号:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"><html><head><title>Application Defined Page Cache.</title><style type="text/css">body {    margin: auto;    font-family: "Verdana" "sans-serif";    padding: 8px 1%;}a { color: #45735f }a:visited { color: #734559 }.logo { position:absolute; margin:3px; }.tagline {  float:right;  text-align:right;  font-style:italic;  width:240px;  margin:12px;  margin-top:58px;}.toolbar {  font-variant: small-caps;  text-align: center;  line-height: 1.6em;  margin: 0;  padding:1px 8px;}.toolbar a { color: white; text-decoration: none; padding: 6px 12px; }.toolbar a:visited { color: white; }.toolbar a:hover { color: #80a796; background: white; }.content    { margin: 5%; }.content dt { font-weight:bold; }.content dd { margin-bottom: 25px; margin-left:20%; }.content ul { padding:0px; padding-left: 15px; margin:0px; }/* rounded corners */.se  { background: url(../images/se.png) 100% 100% no-repeat #80a796}.sw  { background: url(../images/sw.png) 0% 100% no-repeat }.ne  { background: url(../images/ne.png) 100% 0% no-repeat }.nw  { background: url(../images/nw.png) 0% 0% no-repeat }</style><meta http-equiv="content-type" content="text/html; charset=UTF-8">  </head><body><div><!-- container div to satisfy validator --><a href="../index.html"><img class="logo" src="../images/SQLite.gif" alt="SQLite Logo" border="0"></a><div><!-- IE hack to prevent disappearing logo--></div><div class="tagline">Small. Fast. Reliable.<br>Choose any three.</div><table width=100% style="clear:both"><tr><td>  <div class="se"><div class="sw"><div class="ne"><div class="nw">  <div class="toolbar">    <a href="../about.html">About</a>    <a href="../sitemap.html">Sitemap</a>    <a href="../docs.html">Documentation</a>    <a href="../download.html">Download</a>    <a href="../copyright.html">License</a>    <a href="../news.html">News</a>    <a href="http://www.sqlite.org/cvstrac/index">Developers</a>    <a href="../support.html">Support</a>  </div></div></div></div></div></td></tr></table>  <a href="intro.html"><h2>SQLite C Interface</h2></a><h2>Application Defined Page Cache.</h2><blockquote><pre>typedef struct sqlite3_pcache_methods sqlite3_pcache_methods;struct sqlite3_pcache_methods {  void *pArg;  int (*xInit)(void*);  void (*xShutdown)(void*);  sqlite3_pcache *(*xCreate)(int szPage, int bPurgeable);  void (*xCachesize)(sqlite3_pcache*, int nCachesize);  int (*xPagecount)(sqlite3_pcache*);  void *(*xFetch)(sqlite3_pcache*, unsigned key, int createFlag);  void (*xUnpin)(sqlite3_pcache*, void*, int discard);  void (*xRekey)(sqlite3_pcache*, void*, unsigned oldKey, unsigned newKey);  void (*xTruncate)(sqlite3_pcache*, unsigned iLimit);  void (*xDestroy)(sqlite3_pcache*);};</pre></blockquote><p><b>Important:</b> This interface is <a href="../c3ref/experimental.html">experimental</a> and is subject to change without notice.</p><p>The <a href="../c3ref/config.html">sqlite3_config</a>(<a href="../c3ref/c_config_getmalloc.html">SQLITE_CONFIG_PCACHE</a>, ...) interface canregister an alternative page cache implementation by passing in aninstance of the sqlite3_pcache_methods structure. The majority of theheap memory used by sqlite is used by the page cache to cache data readfrom, or ready to be written to, the database file. By implementing acustom page cache using this API, an application can control moreprecisely the amount of memory consumed by sqlite, the way in whichsaid memory is allocated and released, and the policies used todetermine exactly which parts of a database file are cached and forhow long.</p><p>The contents of the structure are copied to an internal buffer by sqlitewithin the call to <a href="../c3ref/config.html">sqlite3_config</a>.</p><p>The xInit() method is called once for each call to <a href="../c3ref/initialize.html">sqlite3_initialize()</a>(usually only once during the lifetime of the process). It is passeda copy of the sqlite3_pcache_methods.pArg value. It can be used to setup global structures and mutexes required by the custom page cacheimplementation. The xShutdown() method is called from within<a href="../c3ref/initialize.html">sqlite3_shutdown()</a>, if the application invokes this API. It can be usedto clean up any outstanding resources before process shutdown, if required.</p><p>The xCreate() method is used to construct a new cache instance. Thefirst parameter, szPage, is the size in bytes of the pages that mustbe allocated by the cache. szPage will not be a power of two. Thesecond argument, bPurgeable, is true if the cache being created willbe used to cache database pages read from a file stored on disk, orfalse if it is used for an in-memory database. The cache implementationdoes not have to do anything special based on the value of bPurgeable,it is purely advisory.</p><p>The xCachesize() method may be called at any time by SQLite to set thesuggested maximum cache-size (number of pages stored by) the cacheinstance passed as the first argument. This is the value configured usingthe 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 special with thisvalue, it is advisory only.</p><p>The xPagecount() method should return the number of pages currentlystored in the cache supplied as an argument.</p><p>The xFetch() method is used to fetch a page and return a pointer to it.A 'page', in this context, is a buffer of szPage bytes aligned at an8-byte boundary. The page to be fetched is determined by the key. Themimimum key value is 1. After it has been retrieved using xFetch, the pageis considered to be pinned.</p><p>If the requested page is already in the page cache, then a pointer tothe cached buffer should be returned with its contents intact. If thepage is not already in the cache, then the expected behaviour of thecache is determined by the value of the createFlag parameter passedto xFetch, according to the following table:</p><p><table border=1 width=85% align=center><tr><th>createFlag<th>Expected Behaviour<tr><td>0<td>NULL should be returned. No new cache entry is created.<tr><td>1<td>If createFlag is set to 1, this indicates thatSQLite is holding pinned pages that can be unpinnedby writing their contents to the database file (arelatively expensive operation). In this situation thecache implementation has two choices: it can return NULL,in which case SQLite will attempt to unpin one or morepages before re-requesting the same page, or it canallocate a new page and return a pointer to it. If a newpage is allocated, then it must be completely zeroed beforeit is returned.<tr><td>2<td>If createFlag is set to 2, then SQLite is not holding anypinned pages associated with the specific cache passedas the first argument to xFetch() that can be unpinned. Thecache implementation should attempt to allocate a newcache entry and return a pointer to it. Again, the newpage should be zeroed before it is returned. If the xFetch()method returns NULL when createFlag==2, SQLite assumes thata memory allocation failed and returns SQLITE_NOMEM to theuser.</table></p><p>xUnpin() is called by SQLite with a pointer to a currently pinned pageas its second argument. If the third parameter, discard, is non-zero,then the page should be evicted from the cache. In this case SQLiteassumes that the next time the page is retrieved from the cache usingthe xFetch() method, it will be zeroed. If the discard parameter iszero, then the page is considered to be unpinned. The cache implementationmay choose to reclaim (free or recycle) unpinned pages at any time.SQLite assumes that next time the page is retrieved from the cacheit will either be zeroed, or contain the same data that it did when itwas unpinned.</p><p>The cache is not required to perform any reference counting. A singlecall to xUnpin() unpins the page regardless of the number of prior callsto xFetch().</p><p>The xRekey() method is used to change the key value associated with thepage passed as the second argument from oldKey to newKey. If the cachepreviously contains an entry associated with newKey, it should bediscarded. Any prior cache entry associated with newKey is guaranteed notto be pinned.</p><p>When SQLite calls the xTruncate() method, the cache must discard allexisting cache entries with page numbers (keys) greater than or equalto the value of the iLimit parameter passed to xTruncate(). If anyof these pages are pinned, they are implicitly unpinned, meaning thatthey can be safely discarded.</p><p>The xDestroy() method is used to delete a cache allocated by xCreate().All resources associated with the specified cache should be freed. Aftercalling 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_methodsfunctions.</p><p>See also lists of  <a href="objlist.html">Objects</a>,  <a href="constlist.html">Constants</a>, and  <a href="funclist.html">Functions</a>.</p><hr><small><i>This page last modified 2008/12/09 18:44:04 UTC</i></small></div></body></html>
⌨️ 快捷键说明

复制代码 Ctrl + C
搜索代码 Ctrl + F
全屏模式 F11
切换主题 Ctrl + Shift + D
显示快捷键 ?
增大字号 Ctrl + =
减小字号 Ctrl + -