capi3ref.html

sqlite3源码,适合作为嵌入式（embedded）

part of system initialization by the sqlite3_initialize() function.
 The xMutexInit routine shall be called by SQLite once for each
effective call to <a href="#sqlite3_initialize">sqlite3_initialize()</a>.</p>

<p>The xMutexEnd method defined by this structure is invoked as
part of system shutdown by the sqlite3_shutdown() function. The
implementation of this method is expected to release all outstanding
resources obtained by the mutex methods implementation, especially
those obtained by the xMutexInit method. The xMutexEnd()
interface shall be invoked once for each call to <a href="#sqlite3_initialize">sqlite3_shutdown()</a>.</p>

<p>The remaining seven methods defined by this structure (xMutexAlloc,
xMutexFree, xMutexEnter, xMutexTry, xMutexLeave, xMutexHeld and
xMutexNotheld) implement the following interfaces (respectively):</p>

<p><ul>
<li>  <a href="#sqlite3_mutex_alloc">sqlite3_mutex_alloc()</a> </li>
<li>  <a href="#sqlite3_mutex_alloc">sqlite3_mutex_free()</a> </li>
<li>  <a href="#sqlite3_mutex_alloc">sqlite3_mutex_enter()</a> </li>
<li>  <a href="#sqlite3_mutex_alloc">sqlite3_mutex_try()</a> </li>
<li>  <a href="#sqlite3_mutex_alloc">sqlite3_mutex_leave()</a> </li>
<li>  <a href="#sqlite3_mutex_held">sqlite3_mutex_held()</a> </li>
<li>  <a href="#sqlite3_mutex_held">sqlite3_mutex_notheld()</a> </li>
</ul></p>

<p>The only difference is that the public sqlite3_XXX functions enumerated
above silently ignore any invocations that pass a NULL pointer instead
of a valid mutex handle. The implementations of the methods defined
by this structure are not required to handle this case, the results
of passing a NULL pointer instead of a valid mutex handle are undefined
(i.e. it is acceptable to provide an implementation that segfaults if
it is passed a NULL pointer).
</p><hr><a name="sqlite3_pcache"></a>
<h2>Custom Page Cache Object</h2><blockquote><pre>typedef struct sqlite3_pcache sqlite3_pcache;
</pre></blockquote><p><b>Important:</b> This interface is <a href="capi3ref.html">experimental</a> and is subject to change without notice.</p><p>
The sqlite3_pcache type is opaque.  It is implemented by
the pluggable module.  The SQLite core has no knowledge of
its size or internal structure and never deals with the
sqlite3_pcache object except by holding and passing pointers
to the object.</p>

<p>See <a href="#sqlite3_pcache_methods">sqlite3_pcache_methods</a> for additional information.
</p><hr><a name="sqlite3_pcache_methods"></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="capi3ref.html">experimental</a> and is subject to change without notice.</p><p>
The <a href="#sqlite3_config">sqlite3_config</a>(<a href="#SQLITE_CONFIG_GETMALLOC">SQLITE_CONFIG_PCACHE</a>, ...) interface can
register an alternative page cache implementation by passing in an
instance of the sqlite3_pcache_methods structure. The majority of the
heap memory used by sqlite is used by the page cache to cache data read
from, or ready to be written to, the database file. By implementing a
custom page cache using this API, an application can control more
precisely the amount of memory consumed by sqlite, the way in which
said 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 contents of the structure are copied to an internal buffer by sqlite
within the call to <a href="#sqlite3_config">sqlite3_config</a>.</p>

<p>The xInit() method is called once for each call to <a href="#sqlite3_initialize">sqlite3_initialize()</a>
(usually only once during the lifetime of the process). It is passed
a copy of the sqlite3_pcache_methods.pArg value. It can be used to set
up global structures and mutexes required by the custom page cache
implementation. The xShutdown() method is called from within
<a href="#sqlite3_initialize">sqlite3_shutdown()</a>, if the application invokes this API. It can be used
to clean up any outstanding resources before process shutdown, if required.</p>

<p>The xCreate() method is used to construct a new cache instance. The
first parameter, szPage, is the size in bytes of the pages that must
be allocated by the cache. szPage will not be a power of two. The
second argument, bPurgeable, is true if the cache being created will
be used to cache database pages read from 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 on the value of bPurgeable,
it is purely advisory.</p>

<p>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 special with this
value, it is advisory only.</p>

<p>The xPagecount() method should return the number of pages currently
stored 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 an
8-byte boundary. The page to be fetched is determined by the key. The
mimimum 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 a pointer to
the cached buffer should be returned with its contents intact. If the
page is not already in the cache, then the expected behaviour of the
cache is determined by the value of the createFlag parameter passed
to 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 that
SQLite is holding pinned pages that can be unpinned
by writing their contents to the database file (a
relatively expensive operation). In this situation the
cache implementation has two choices: it can return NULL,
in which case SQLite will attempt to unpin one or more
pages before re-requesting the same page, or it can
allocate a new page and return a pointer to it. If a new
page is allocated, then it must be completely zeroed before
it is returned.
<tr><td>2<td>If createFlag is set to 2, then SQLite is not holding any
pinned pages associated with the specific cache passed
as the first argument to xFetch() that can be unpinned. The
cache implementation should attempt to allocate a new
cache entry and return a pointer to it. Again, the new
page should be zeroed before it is returned. If the xFetch()
method returns NULL when createFlag==2, SQLite assumes that
a memory allocation failed and returns SQLITE_NOMEM to the
user.
</table></p>

<p>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 should be evicted from the cache. In this case SQLite
assumes that the next time the page is retrieved from the cache using
the xFetch() method, it will be zeroed. If the discard parameter is
zero, then the page is considered to be unpinned. The cache implementation
may choose to reclaim (free or recycle) unpinned pages at any time.
SQLite assumes that next time the page is retrieved from the cache
it will either be zeroed, or contain the same data that it did when it
was unpinned.</p>