34to35.html

嵌入式数据库sqlite 3.5.9的文档

  Within your application, call the procedure implemented in the last
  step above as part of your initialization process before any
  database connections are opened.  
</p>

<h2>3.0 The Memory Allocation Subsystem</h2>
<p>
  Beginning with version 3.5, SQLite obtains all of the heap memory it
  needs using the routines 
<a href="c3ref/free.html">sqlite3_malloc()</a>, 
<a href="c3ref/free.html">sqlite3_free()</a>, and
  
<a href="c3ref/free.html">sqlite3_realloc()</a>.  These routines have existed in prior versions
  of SQLite, but SQLite has previously bypassed these routines and used
  its own memory allocator.  This all changes in version 3.5.0.
</p>

<p>
  The SQLite source tree actually contains multiple versions of the
  memory allocator.  The default high-speed version found in the
  "mem1.c" source file is used for most builds.  But if the SQLITE_MEMDEBUG
  flag is enabled, a separate memory allocator the "mem2.c" source file
  is used instead.  The mem2.c allocator implements lots of hooks to
  do error checking and to simulate memory allocation failures for testing
  purposes.  Both of these allocators use the malloc()/free() implementation
  in the standard C library.
</p>

<p>
  Applications are not required to use either of these standard memory
  allocators.  If SQLite is compiled with SQLITE_OMIT_MEMORY_ALLOCATION
  then no implementation for the 
<a href="c3ref/free.html">sqlite3_malloc()</a>, 
<a href="c3ref/free.html">sqlite3_realloc()</a>,
  and 
<a href="c3ref/free.html">sqlite3_free()</a> functions is provided.  Instead, the application
  that links against SQLite must provide its own implementation of these
  functions.  The application provided memory allocator is not required
  to use the malloc()/free() implementation in the standard C library.
  An embedded application might provide an alternative memory allocator
  that uses memory for a fixed memory pool set aside for the exclusive
  use of SQLite, for example.
</p>

<p>
  Applications that implement their own memory allocator must provide
  implementation for the usual three allocation functions 
  
<a href="c3ref/free.html">sqlite3_malloc()</a>, 
<a href="c3ref/free.html">sqlite3_realloc()</a>, and 
<a href="c3ref/free.html">sqlite3_free()</a>.
  And they must also implement a fourth function:
</p>

<blockquote><pre>

int sqlite3_memory_alarm(
  void(*xCallback)(void *pArg, sqlite3_int64 used, int N),
  void *pArg,
  sqlite3_int64 iThreshold
);

</pre></blockquote>
<p>
 The 
<a href="c3ref/aggregate_count.html">sqlite3_memory_alarm</a> routine is used to register
 a callback on memory allocation events.
 This routine registers or clears a callbacks that fires when
 the amount of memory allocated exceeds iThreshold.  Only
 a single callback can be registered at a time.  Each call
 to 
<a href="c3ref/aggregate_count.html">sqlite3_memory_alarm()</a> overwrites the previous callback.
 The callback is disabled by setting xCallback to a NULL
 pointer.
</p>

<p>
 The parameters to the callback are the pArg value, the 
 amount of memory currently in use, and the size of the
 allocation that provoked the callback.  The callback will
 presumably invoke 
<a href="c3ref/free.html">sqlite3_free()</a> to free up memory space.
 The callback may invoke 
<a href="c3ref/free.html">sqlite3_malloc()</a> or 
<a href="c3ref/free.html">sqlite3_realloc()</a>
 but if it does, no additional callbacks will be invoked by
 the recursive calls.
</p>

<p>
 The 
<a href="c3ref/soft_heap_limit.html">sqlite3_soft_heap_limit()</a> interface works by registering
 a memory alarm at the soft heap limit and invoking 
 
<a href="c3ref/release_memory.html">sqlite3_release_memory()</a> in the alarm callback.  Application
 programs should not attempt to use the 
<a href="c3ref/aggregate_count.html">sqlite3_memory_alarm()</a>
 interface because doing so will interfere with the
 
<a href="c3ref/soft_heap_limit.html">sqlite3_soft_heap_limit()</a> module.  This interface is exposed
 only so that applications can provide their own
 alternative implementation when the SQLite core is
 compiled with SQLITE_OMIT_MEMORY_ALLOCATION.
</p>

<p>
  The built-in memory allocators in SQLite also provide the following
  additional interfaces:
</p>

<blockquote><pre>

sqlite3_int64 sqlite3_memory_used(void);
sqlite3_int64 sqlite3_memory_highwater(int resetFlag);

</pre></blockquote>
<p>
  These interfaces can be used by an application to monitor how
  much memory SQLite is using.  The 
<a href="c3ref/memory_highwater.html">sqlite3_memory_used()</a> routine
  returns the number of bytes of memory currently in use and the
  
<a href="c3ref/memory_highwater.html">sqlite3_memory_highwater()</a> returns the maximum instantaneous
  memory usage.  Neither routine includes the overhead associated
  with the memory allocator.  These routines are provided for use
  by the application.  SQLite never invokes them itself.  So if
  the application is providing its own memory allocation subsystem,
  it can omit these interfaces if desired.
</p>

<h2>4.0 The Mutex Subsystem</h2>
<p>
  SQLite has always been threadsafe in the sense that it is safe to
  use different SQLite database connections in different threads at the
  same time.  The constraint was that the same database connection
  could not be used in two separate threads at once.  SQLite version 3.5.0
  relaxes this constraint. 
</p>

<p>
  In order to allow multiple threads to use the same database connection
  at the same time, SQLite must make extensive use of mutexes.  And for
  this reason a new mutex subsystem as been added.  The mutex subsystem
  as the following interface:
</p>

<blockquote><pre>

sqlite3_mutex *sqlite3_mutex_alloc(int);
void sqlite3_mutex_free(sqlite3_mutex*);
void sqlite3_mutex_enter(sqlite3_mutex*);
int sqlite3_mutex_try(sqlite3_mutex*);
void sqlite3_mutex_leave(sqlite3_mutex*);

</pre></blockquote>
<p>
  Though these routines exist for the use of the SQLite core, 
  application code is free to use these routines as well, if desired.
  A mutex is an 
<a href="c3ref/mutex.html">sqlite3_mutex</a> object.  The 
<a href="c3ref/mutex_alloc.html">sqlite3_mutex_alloc()</a>
  routine allocates a new mutex object and returns a pointer to it.
  The argument to 
<a href="c3ref/mutex_alloc.html">sqlite3_mutex_alloc()</a> should be 
  
<a href="c3ref/c_mutex_fast.html">SQLITE_MUTEX_FAST</a> or 
<a href="c3ref/c_mutex_fast.html">SQLITE_MUTEX_RECURSIVE</a> for non-recursive
  and recursive mutexes, respectively.  If the underlying system does
  not provide non-recursive mutexes, then a recursive mutex can be
  substituted in that case.  The argument to 
<a href="c3ref/mutex_alloc.html">sqlite3_mutex_alloc()</a>
  can also be a constant designating one of several static mutexes:
  <ul>
  <li>  
<a href="c3ref/c_mutex_fast.html">SQLITE_MUTEX_STATIC_MASTER</a>
  <li>  
<a href="c3ref/c_mutex_fast.html">SQLITE_MUTEX_STATIC_MEM</a>
  <li>  
<a href="c3ref/c_mutex_fast.html">SQLITE_MUTEX_STATIC_MEM2</a>
  <li>  
<a href="c3ref/c_mutex_fast.html">SQLITE_MUTEX_STATIC_PRNG</a>
  <li>  
<a href="c3ref/c_mutex_fast.html">SQLITE_MUTEX_STATIC_LRU</a>
  </ul>
  These static mutexes are reserved for use internally by SQLite
  and should not be used by the application.  The static mutexes
  are all non-recursive.
</p>

<p>
  The 
<a href="c3ref/mutex_alloc.html">sqlite3_mutex_free()</a> routine should be used to deallocate
  a non-static mutex.  If a static mutex is passed to this routine
  then the behavior is undefined.
</p>

<p>
  The 
<a href="c3ref/mutex_alloc.html">sqlite3_mutex_enter()</a> attempts to enter the mutex and blocks
  if another threads is already there.  
<a href="c3ref/mutex_alloc.html">sqlite3_mutex_try()</a> attempts
  to enter and returns 
<a href="c3ref/c_abort.html">SQLITE_OK</a> on success or 
<a href="c3ref/c_abort.html">SQLITE_BUSY</a> if another
  thread is already there.  
<a href="c3ref/mutex_alloc.html">sqlite3_mutex_leave()</a> exits a mutex.
  The mutex is held until the number of exits matches the number of
  entrances.  If 
<a href="c3ref/mutex_alloc.html">sqlite3_mutex_leave()</a> is called on a mutex that 
  the thread is not currently holding, then the behavior is undefined.
  If any routine is called for a deallocated mutex, then the behavior
  is undefined.
</p>

<p>
  The SQLite source code provides multiple implementations of these
  APIs, suitable for varying environments.  If SQLite is compiled with
  the SQLITE_THREADSAFE=0 flag then a no-op mutex implementation that 
  is fast but does no real mutual exclusion is provided.  That 
  implementation is suitable for use in single-threaded applications
  or applications that only use SQLite in a single thread.  Other
  real mutex implementations are provided based on the underlying
  operating system.
</p>

<p>
  Embedded applications may wish to provide their own mutex implementation.
  If SQLite is compiled with the -DSQLITE_MUTEX_APPDEF=1 compile-time flag
  then the SQLite core provides no mutex subsystem and a mutex subsystem
  that matches the interface described above must be provided by the
  application that links against SQLite.
</p>

<h2>5.0 Other Interface Changes</h2>
<p>
  Version 3.5.0 of SQLite changes the behavior of a few APIs in ways
  that are technically incompatible.  However, these APIs are seldom
  used and even when they are used it is difficult to imagine a
  scenario where the change might break something.  The changes
  actually makes these interface much more useful and powerful.
</p>

<p>
  Prior to version 3.5.0, the 
<a href="c3ref/enable_shared_cache.html">sqlite3_enable_shared_cache()</a> API
  would enable and disable the shared cache feature for all connections
  within a single thread - the same thread from which the 
  sqlite3_enable_shared_cache() routine was called.  Database connections
  that used the shared cache were restricted to running in the same
  thread in which they were opened.  Beginning with version 3.5.0,
  the sqlite3_enable_shared_cache() applies to all database connections
  in all threads within the process.  Now database connections running
  in separate threads can share a cache.  And database connections that
  use shared cache can migrate from one thread to another.
</p>

<p>
  Prior to version 3.5.0 the 
<a href="c3ref/soft_heap_limit.html">sqlite3_soft_heap_limit()</a> set an upper
  bound on heap memory usage for all database connections within a
  single thread.  Each thread could have its own heap limit.  Beginning
  in version 3.5.0, there is a single heap limit for the entire process.
  This seems more restrictive (one limit as opposed to many) but in
  practice it is what most users want.
</p>

<p>
  Prior to version 3.5.0 the 
<a href="c3ref/release_memory.html">sqlite3_release_memory()</a> function would
  try to reclaim memory from all database connections in the same thread
  as the sqlite3_release_memory() call.  Beginning with version 3.5.0,
  the sqlite3_release_memory() function will attempt to reclaim memory
  from all database connections in all threads.
</p>

<h2>6.0 Summary</h2>
<p>
  The transition from SQLite version 3.4.2 to 3.5.0 is a major change.
  Every source code file in the SQLite core had to be modified, some
  extensively.  And the change introduced some minor incompatibilities
  in the C interface.  But we feel that the benefits of the transition
  from 3.4.2 to 3.5.0 far outweigh the pain of porting.  The new
  VFS layer is now well-defined and stable and should simplify future
  customizations.  The VFS layer, and the separable memory allocator
  and mutex subsystems allow a standard SQLite source code amalgamation
  to be used in an embedded project without change, greatly simplifying
  configuration management.  And the resulting system is much more
  tolerant of highly threaded designs.
</p>



<hr><small><i>
This page last modified 2008/05/08 14:19:58 UTC
</i></small></div></body></html>