Configuration Options

#define SQLITE_CONFIG_SINGLETHREAD  1  /* nil */
#define SQLITE_CONFIG_MULTITHREAD   2  /* nil */
#define SQLITE_CONFIG_SERIALIZED    3  /* nil */
#define SQLITE_CONFIG_MALLOC        4  /* sqlite3_mem_methods* */
#define SQLITE_CONFIG_GETMALLOC     5  /* sqlite3_mem_methods* */
#define SQLITE_CONFIG_SCRATCH       6  /* void*, int sz, int N */
#define SQLITE_CONFIG_PAGECACHE     7  /* void*, int sz, int N */
#define SQLITE_CONFIG_HEAP          8  /* void*, int nByte, int min */
#define SQLITE_CONFIG_MEMSTATUS     9  /* boolean */
#define SQLITE_CONFIG_MUTEX        10  /* sqlite3_mutex_methods* */
#define SQLITE_CONFIG_GETMUTEX     11  /* sqlite3_mutex_methods* */

These constants are the available integer configuration options that can be passed as the first argument to the sqlite3_config() interface.

New configuration options may be added in future releases of SQLite. Existing configuration options might be discontinued. Applications should check the return code from sqlite3_config() to make sure that the call worked. The sqlite3_config() interface will return a non-zero error code if a discontinued or unsupported configuration option is invoked.

SQLITE_CONFIG_SINGLETHREAD

There are no arguments to this option. This option disables all mutexing and puts SQLite into a mode where it can only be used by a single thread.

SQLITE_CONFIG_MULTITHREAD

There are no arguments to this option. This option disables mutexing on database connection and prepared statement objects. The application is responsible for serializing access to database connections and prepared statements. But other mutexes are enabled so that SQLite will be safe to use in a multi-threaded environment.

SQLITE_CONFIG_SERIALIZED

There are no arguments to this option. This option enables all mutexes including the recursive mutexes on database connection and prepared statement objects. In this mode (which is the default when SQLite is compiled with SQLITE_THREADSAFE=1) the SQLite library will itself serialize access to database connections and prepared statements so that the application is free to use the same database connection or the same prepared statement in different threads at the same time.

This configuration option merely sets the default mutex behavior to serialize access to database connections. Individual database connections can override this setting using the SQLITE_OPEN_NOMUTEX flag to sqlite3_open_v2().

SQLITE_CONFIG_MALLOC

This option takes a single argument which is a pointer to an instance of the sqlite3_mem_methods structure. The argument specifies alternative low-level memory allocation routines to be used in place of the memory allocation routines built into SQLite.

SQLITE_CONFIG_GETMALLOC

This option takes a single argument which is a pointer to an instance of the sqlite3_mem_methods structure. The sqlite3_mem_methods structure is filled with the currently defined memory allocation routines. This option can be used to overload the default memory allocation routines with a wrapper that simulations memory allocation failure or tracks memory usage, for example.

SQLITE_CONFIG_MEMSTATUS

This option takes single boolean argument which enables or disables the collection of memory allocation statistics. When disabled, the following SQLite interfaces become non-operational:

• sqlite3_memory_used()
• sqlite3_memory_highwater()
• sqlite3_soft_heap_limit()
• sqlite3_memory_status()

SQLITE_CONFIG_SCRATCH

This option specifies a static memory buffer that SQLite can use for scratch memory. There are three arguments: A pointer to the memory, the size of each scratch buffer (sz), and the number of buffers (N). The sz argument must be a multiple of 16. The first argument should point to an allocation of at least (sz+4)*N bytes of memory. SQLite will use no more than one scratch buffer at once per thread, so N should be set to the expected maximum number of threads. The sz parameter should be 6 times the size of the largest database page size. Scratch buffers are used as part of the btree balance operation. If The btree balancer needs additional memory beyond what is provided by scratch buffers or if no scratch buffer space is specified, then SQLite goes to sqlite3_malloc() to obtain the memory it needs.

SQLITE_CONFIG_PAGECACHE

This option specifies a static memory buffer that SQLite can use for the database page cache. There are three arguments: A pointer to the memory, the size of each page buffer (sz), and the number of pages (N). The sz argument must be a power of two between 512 and 32768. The first argument should point to an allocation of at least (sz+4)*N bytes of memory. SQLite will use the memory provided by the first argument to satisfy its memory needs for the first N pages that it adds to cache. If additional page cache memory is needed beyond what is provided by this option, then SQLite goes to sqlite3_malloc() for the additional storage space.

SQLITE_CONFIG_HEAP

This option specifies a static memory buffer that SQLite will use for all of its dynamic memory allocation needs beyond those provided for by SQLITE_CONFIG_SCRATCH and SQLITE_CONFIG_PAGECACHE. There are three arguments: A pointer to the memory, the number of bytes in the memory buffer, and the minimum allocation size. If the first pointer (the memory pointer) is NULL, then SQLite reverts to using its default memory allocator (the system malloc() implementation), undoing any prior invocation of SQLITE_CONFIG_MALLOC. If the memory pointer is not NULL and either SQLITE_ENABLE_MEMSYS3 or SQLITE_ENABLE_MEMSYS5 are defined, then the alternative memory allocator is engaged to handle all of SQLites memory allocation needs.

SQLITE_CONFIG_MUTEX

This option takes a single argument which is a pointer to an instance of the sqlite3_mutex_methods structure. The argument specifies alternative low-level mutex routines to be used in place the mutex routines built into SQLite.

SQLITE_CONFIG_GETMUTEX

This option takes a single argument which is a pointer to an instance of the sqlite3_mutex_methods structure. The sqlite3_mutex_methods structure is filled with the currently defined mutex routines. This option can be used to overload the default mutex allocation routines with a wrapper used to track mutex usage for performance profiling or testing, for example.

See also lists of Objects, Constants, and Functions.

---

This page last modified 2008/06/18 13:48:19 UTC