custombuild.html

sqlite的帮助文档

<blockquote><pre>
sqlite3_config(SQLITE_CONFIG_SINGLETHREAD);
</pre></blockquote>

<p>Disabling mutexes at run-time is not as effective as disabling them
at compile-time since SQLite still must do a test of a boolean variable
to see if mutexes are enabled or disabled at each point where a mutex
might be required.  But there is still a performance advantage for
disabling mutexes at run-time.</p>

<p>For multi-threaded applications that are careful about how they
manage threads, SQLite supports an alternative run-time configuration
that is half way between not using any mutexes and the default situation
of mutexing everything in sight.  This in-the-middle mutex alignment can
be established as follows:</p>

<blockquote><pre>
sqlite3_config(SQLITE_CONFIG_MULTITHREAD);
sqlite3_config(SQLITE_CONFIG_MEMSTATUS, 0);
</pre></blockquote>

<p>There are two separate configuration changes here which can
be used either togethr or separately. The
<a href="c3ref/c_config_getmalloc.html">SQLITE_CONFIG_MULTITHREAD</a> setting disables the mutexes that
serialize access to <a href="c3ref/sqlite3.html">database connection</a> objects and 
<a href="c3ref/stmt.html">prepared statement</a> objects.  With this setting, the application
is free to use SQLite from multiple threads, but it must make sure
than no two threads try to access the same <a href="c3ref/sqlite3.html">database connection</a>
or any <a href="c3ref/stmt.html">prepared statements</a> associated with the same 
<a href="c3ref/sqlite3.html">database connection</a> at the same time.  Two threads can use SQLite
at the same time, but they must use separate <a href="c3ref/sqlite3.html">database connections</a>.
The second <a href="c3ref/c_config_getmalloc.html">SQLITE_CONFIG_MEMSTATUS</a> setting disables the mechanism
in SQLite that tracks the total size of all outstanding memory
allocation requests.  This omits the need to mutex each call
to <a href="c3ref/free.html">sqlite3_malloc()</a> and <a href="c3ref/free.html">sqlite3_free()</a>, which saves a huge
number of mutex operations.  But a consequence of disabling the
memory statistics mechanism is that the 
<a href="c3ref/memory_highwater.html">sqlite3_memory_used()</a>, <a href="c3ref/memory_highwater.html">sqlite3_memory_highwater()</a>, and
<a href="c3ref/soft_heap_limit.html">sqlite3_soft_heap_limit()</a> interfaces cease to work.
</p>

<p>SQLite uses pthreads for its mutex implementation on Unix and
SQLite requires a recursive mutex.  Most modern pthread implementations
support recursive mutexes, but not all do.  For systems that do not
support recursive mutexes, it is recommended that applications operate
in single-threaded mode only.  If this is not possible, SQLite provides
an alternative recursive mutex implementation built on top of the
standard "fast" mutexes of pthreads.  This alternative
implementation should work correctly as long as pthread_equal() is
atomic and the processor has a coherient data cache.  The alternative
recursive mutex implementation is enabled by the following
compiler command-line switch:</p>

<blockquote><pre>
-DSQLITE_HOMEGROWN_RECURSIVE_MUTEX=1
</pre></blockquote>

<p>When porting SQLite to a new operating system, it is usually necessary
to completely replace the built-in mutex subsystem with an alternative
built around the mutex primitives of the new operating system.  This
is accomplished by compiling SQLite with the following option:</p>

<blockquote><pre>
-DSQLITE_MUTEX_APPDEF=1
</pre></blockquote>

<p>When SQLite is compiled with the SQLITE_MUTEX_APPDEF=1 option, it
completely omits the implementation of its 
<a href="c3ref/mutex_alloc.html">mutex primitive functions</a>.  But the SQLite
library still attempts to call these functions where necessary, so the
application must itself implement the
<a href="c3ref/mutex_alloc.html">mutex primitive functions</a> and link them together
with SQLite.</p>

<h2>3.0 Configuring Or Replacing The Memory Allocation Subsystem</h2>

<p>By default, SQLite obtains the memory it needs for objects and
cache from the malloc()/free() implementation of the standard library.
There is also on-going work with experimental memory allocators that
satisfy all memory requests from a single fixed memory buffer handed
to SQLite at application start.  Additional information on these
experimental memory allocators will be provided in a future revision
of this document.</p>

<p>SQLite supports the ability of an application to specify an alternative
memory allocator at run-time using the <a href="c3ref/config.html">sqlite3_config()</a> interface.
For example:</p>

<blockquote><pre>
sqlite3_config(SQLITE_CONFIG_MALLOC, dlmalloc, dlfree, dlrealloc, dlmalloc_usable_size);
</pre></blockquote>

<p>The <a href="c3ref/c_config_getmalloc.html">SQLITE_CONFIG_MALLOC</a> setting to <a href="c3ref/config.html">sqlite3_config()</a> passes four
function pointers into SQLite.  The first three functions work exactly
like malloc(), free(), and realloc(), respectively, from the standard
C library.  The fourth function pointer must be for a routine that
returns the size of a memory allocation given a pointer to that allocation.
In the default memory allocator implementation for SQLite, these fourth
"memsize" function is implemented by prepending an 8-byte size integer
to the beginning of every allocation.  The memsize function is not a
standard part of must memory alloction libraries and so must be implemented
in this way.  However, Doug Lea's dlmalloc implementation, as shown in the
example above, does provide an implementation of memsize which, if used,
reduces the size overhead and execution time of every memory allocation
and deallocation.</p>

<p><i>TBD: Talk about alternative zero-malloc implementations and how to
select them at compile-time.</i></p>

<p><i>TBD: Talk about how to disable any built-in memory allocator so that
an application is required to register the memory allocator at
startup.</i></p>

<h2>4.0 Adding New Virtual File Systems</h2>

<p>Since <a href="releaselog/3_5_0.html">version 3.5.0</a>, SQLite has supported an interface called the
<a href="c3ref/vfs.html">virtual file system</a> or "VFS".
This object is somewhat misnamed since it
is really an interface to whole underlying operating system,
just the filesystem.</p>

<p> One of the interesting features
of the VFS interface is that SQLite can support multiple VFSes at the
same time.  Each <a href="c3ref/sqlite3.html">database connection</a> has to choose a single VFS for its
use when the connection is first opened using <a href="c3ref/open.html">sqlite3_open_v2()</a>.
But if a process contains multiple <a href="c3ref/sqlite3.html">database connections</a> each can choose
a different VFS.  VFSes can be added at run-time using the
<a href="c3ref/vfs_find.html">sqlite3_vfs_register()</a> interface.</p>

<p>The default builds for SQLite on Unix, Windows, and OS/2 include 
a VFS appropriate for the target platform.  SQLite builds for other
operating systems do not contain a VFS by default, but the application
can register one or more at run-time.</p>

<h2>5.0 Porting SQLite To A New Operating System</h2>

<p>In order to port SQLite to a new operating system - an operating
system not supported by default - the application
must provide...</p>

<ul>
<li> a working mutex subsystem (but only if it is multithreaded), </li>
<li> a working memory allocation subsystem (assuming it lacks malloc()
in its standard library), and</li>
<li> a working VFS implementation.</li>
</ul>

<p>All of these things can be provided in a single auxiliary C code file
and then linked with the stock "sqlite3.c" code file to generate a working
SQLite build for the target operating system.  In addition to the
alternative mutex and memory allocation subsystems and the new VFS,
the auxiliary C code file should contain implementations for the
following two routines:</p>

<ul>
<li> <a href="c3ref/initialize.html">sqlite3_initialize()</a> </li>
<li> <a href="c3ref/initialize.html">sqlite3_shutdown()</a> </li>
</ul>

<p>The "sqlite3.c" code file contains default implementations of a VFS
and of the <a href="c3ref/initialize.html">sqlite3_initialize()</a> and <a href="c3ref/initialize.html">sqlite3_shutdown()</a> functions that
are appropriate for Unix, Windows, and OS/2.
To prevent one of these default components from being loaded when sqlite3.c
is compiled, it is necessary to add the following compile-time
option:</p>

<blockquote><pre>
-DSQLITE_OS_OTHER=1
</pre></blockquote>

<p>

<p>The SQLite core will call <a href="c3ref/initialize.html">sqlite3_initialize()</a> early.  The auxiliary
C code file can contain an implementation of sqlite3_initialize() that
registers an appropriate VFS and also perhaps initializes an alternative
mutex system (if mutexes are required) or does any memory allocation
subsystem initialization that is required.
The SQLite core never calls <a href="c3ref/initialize.html">sqlite3_shutdown()</a> but it is part of the
official SQLite API and is not otherwise provided when compiled with
-DSQLITE_OS_OTHER=1, so the auxiliary C code file should probably provide
it for completeness.</p>


<p>
<hr><small><i>
This page last modified 2008/11/01 13:26:49 UTC
</i></small></div></body></html>