sqlite/man/SQLITE_CONFIG_SINGLETHREAD.3

.Dd $Mdocdate$
.Dt SQLITE_CONFIG_SINGLETHREAD 3
.Os
.Sh NAME
.Nm SQLITE_CONFIG_SINGLETHREAD ,
.Nm SQLITE_CONFIG_MULTITHREAD ,
.Nm SQLITE_CONFIG_SERIALIZED ,
.Nm SQLITE_CONFIG_MALLOC ,
.Nm SQLITE_CONFIG_GETMALLOC ,
.Nm SQLITE_CONFIG_SCRATCH ,
.Nm SQLITE_CONFIG_PAGECACHE ,
.Nm SQLITE_CONFIG_HEAP ,
.Nm SQLITE_CONFIG_MEMSTATUS ,
.Nm SQLITE_CONFIG_MUTEX ,
.Nm SQLITE_CONFIG_GETMUTEX ,
.Nm SQLITE_CONFIG_LOOKASIDE ,
.Nm SQLITE_CONFIG_PCACHE ,
.Nm SQLITE_CONFIG_GETPCACHE ,
.Nm SQLITE_CONFIG_LOG ,
.Nm SQLITE_CONFIG_URI ,
.Nm SQLITE_CONFIG_PCACHE2 ,
.Nm SQLITE_CONFIG_GETPCACHE2 ,
.Nm SQLITE_CONFIG_COVERING_INDEX_SCAN ,
.Nm SQLITE_CONFIG_SQLLOG ,
.Nm SQLITE_CONFIG_MMAP_SIZE ,
.Nm SQLITE_CONFIG_WIN32_HEAPSIZE
.Nd Configuration Options
.Sh SYNOPSIS
.Fd #define SQLITE_CONFIG_SINGLETHREAD
.Fd #define SQLITE_CONFIG_MULTITHREAD
.Fd #define SQLITE_CONFIG_SERIALIZED
.Fd #define SQLITE_CONFIG_MALLOC
.Fd #define SQLITE_CONFIG_GETMALLOC
.Fd #define SQLITE_CONFIG_SCRATCH
.Fd #define SQLITE_CONFIG_PAGECACHE
.Fd #define SQLITE_CONFIG_HEAP
.Fd #define SQLITE_CONFIG_MEMSTATUS
.Fd #define SQLITE_CONFIG_MUTEX
.Fd #define SQLITE_CONFIG_GETMUTEX
.Fd #define SQLITE_CONFIG_LOOKASIDE
.Fd #define SQLITE_CONFIG_PCACHE
.Fd #define SQLITE_CONFIG_GETPCACHE
.Fd #define SQLITE_CONFIG_LOG
.Fd #define SQLITE_CONFIG_URI
.Fd #define SQLITE_CONFIG_PCACHE2
.Fd #define SQLITE_CONFIG_GETPCACHE2
.Fd #define SQLITE_CONFIG_COVERING_INDEX_SCAN
.Fd #define SQLITE_CONFIG_SQLLOG
.Fd #define SQLITE_CONFIG_MMAP_SIZE
.Fd #define SQLITE_CONFIG_WIN32_HEAPSIZE
.Sh DESCRIPTION
These constants are the available integer configuration options that
can be passed as the first argument to the sqlite3_config()
interface.
.Pp
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.
.Bl -tag -width Ds
.It SQLITE_CONFIG_SINGLETHREAD
There are no arguments to this option.
This option sets the threading mode to Single-thread.
In other words, it disables all mutexing and puts SQLite into a mode
where it can only be used by a single thread.
If SQLite is compiled with the  SQLITE_THREADSAFE=0
compile-time option then it is not possible to change the threading mode
from its default value of Single-thread and so sqlite3_config()
will return SQLITE_ERROR if called with the SQLITE_CONFIG_SINGLETHREAD
configuration option.
.It SQLITE_CONFIG_MULTITHREAD
There are no arguments to this option.
This option sets the threading mode to Multi-thread.
In other words, it 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 as long as no two threads attempt to use
the same database connection at the same time.
If SQLite is compiled with the  SQLITE_THREADSAFE=0
compile-time option then it is not possible to set the Multi-thread
threading mode and sqlite3_config() will
return SQLITE_ERROR if called with the SQLITE_CONFIG_MULTITHREAD
configuration option.
.It SQLITE_CONFIG_SERIALIZED
There are no arguments to this option.
This option sets the threading mode to Serialized.
In other words, 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.
If SQLite is compiled with the  SQLITE_THREADSAFE=0
compile-time option then it is not possible to set the Serialized threading mode
and sqlite3_config() will return SQLITE_ERROR
if called with the SQLITE_CONFIG_SERIALIZED configuration option.
.It 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 makes its own private copy of the content of the sqlite3_mem_methods
structure before the sqlite3_config() call returns.
.It 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.
.It SQLITE_CONFIG_MEMSTATUS
This option takes single argument of type int, interpreted as a boolean,
which enables or disables the collection of memory allocation statistics.
When memory allocation statistics are disabled, the following SQLite
interfaces become non-operational:
.Bl -bullet
.It
sqlite3_memory_used()
.It
sqlite3_memory_highwater()
.It
sqlite3_soft_heap_limit64()
.It
sqlite3_status()
.El
.Pp
Memory allocation statistics are enabled by default unless SQLite is
compiled with SQLITE_DEFAULT_MEMSTATUS=0 in
which case memory allocation statistics are disabled by default.
.It SQLITE_CONFIG_SCRATCH
This option specifies a static memory buffer that SQLite can use for
scratch memory.
There are three arguments:  A pointer an 8-byte aligned memory buffer
from which the scratch allocations will be drawn, the size of each
scratch allocation (sz), and the maximum number of scratch allocations
(N).
The sz argument must be a multiple of 16.
The first argument must be a pointer to an 8-byte aligned buffer of
at least sz*N bytes of memory.
SQLite will use no more than two scratch buffers per thread.
So N should be set to twice the expected maximum number of threads.
SQLite will never require a scratch buffer that is more than 6 times
the database page size.
If SQLite needs needs additional scratch memory beyond what is provided
by this configuration option, then sqlite3_malloc()
will be used to obtain the memory needed.
.It SQLITE_CONFIG_PAGECACHE
This option specifies a static memory buffer that SQLite can use for
the database page cache with the default page cache implementation.
This configuration should not be used if an application-define page
cache implementation is loaded using the SQLITE_CONFIG_PCACHE2 option.
There are three arguments to this option: A pointer to 8-byte aligned
memory, the size of each page buffer (sz), and the number of pages
(N).
The sz argument should be the size of the largest database page (a
power of two between 512 and 32768) plus a little extra for each page
header.
The page header size is 20 to 40 bytes depending on the host architecture.
It is harmless, apart from the wasted memory, to make sz a little too
large.
The first argument should point to an allocation of at least sz*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.
The pointer in the first argument must be aligned to an 8-byte boundary
or subsequent behavior of SQLite will be undefined.
.It 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: An 8-byte aligned 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.
The first pointer (the memory pointer) must be aligned to an 8-byte
boundary or subsequent behavior of SQLite will be undefined.
The minimum allocation size is capped at 2**12.
Reasonable values for the minimum allocation size are 2**5 through
2**8.
.It 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 makes a copy of the content of the sqlite3_mutex_methods
structure before the call to sqlite3_config() returns.
If SQLite is compiled with the  SQLITE_THREADSAFE=0
compile-time option then the entire mutexing subsystem is omitted from
the build and hence calls to sqlite3_config() with
the SQLITE_CONFIG_MUTEX configuration option will return SQLITE_ERROR.
.It 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.
If SQLite is compiled with the  SQLITE_THREADSAFE=0
compile-time option then the entire mutexing subsystem is omitted from
the build and hence calls to sqlite3_config() with
the SQLITE_CONFIG_GETMUTEX configuration option will return SQLITE_ERROR.
.It SQLITE_CONFIG_LOOKASIDE
This option takes two arguments that determine the default memory allocation
for the lookaside memory allocator on each database connection.
The first argument is the size of each lookaside buffer slot and the
second is the number of slots allocated to each database connection.
This option sets the <i>default</i> lookaside size.
The SQLITE_DBCONFIG_LOOKASIDE verb to sqlite3_db_config()
can be used to change the lookaside configuration on individual connections.
.It SQLITE_CONFIG_PCACHE2
This option takes a single argument which is a pointer to an sqlite3_pcache_methods2
object.
This object specifies the interface to a custom page cache implementation.
SQLite makes a copy of the object and uses it for page cache memory
allocations.
.It SQLITE_CONFIG_GETPCACHE2
This option takes a single argument which is a pointer to an sqlite3_pcache_methods2
object.
SQLite copies of the current page cache implementation into that object.
.It SQLITE_CONFIG_LOG
The SQLITE_CONFIG_LOG option is used to configure the SQLite global
error log.
( The SQLITE_CONFIG_LOG option takes two arguments: a pointer to a
function with a call signature of void(*)(void*,int,const char*), and
a pointer to void.
If the function pointer is not NULL, it is invoked by sqlite3_log()
to process each logging event.
If the function pointer is NULL, the sqlite3_log() interface
becomes a no-op.
The void pointer that is the second argument to SQLITE_CONFIG_LOG is
passed through as the first parameter to the application-defined logger
function whenever that function is invoked.
The second parameter to the logger function is a copy of the first
parameter to the corresponding sqlite3_log() call and
is intended to be a result code or an extended result code.
The third parameter passed to the logger is log message after formatting
via sqlite3_snprintf().
The SQLite logging interface is not reentrant; the logger function
supplied by the application must not invoke any SQLite interface.
In a multi-threaded application, the application-defined logger function
must be threadsafe.
.It SQLITE_CONFIG_URI This option takes a single argument of type int.
If non-zero, then URI handling is globally enabled.
If the parameter is zero, then URI handling is globally disabled.
If URI handling is globally enabled, all filenames passed to sqlite3_open(),
sqlite3_open_v2(), sqlite3_open16()
or specified as part of ATTACH commands are interpreted as URIs,
regardless of whether or not the SQLITE_OPEN_URI flag
is set when the database connection is opened.
If it is globally disabled, filenames are only interpreted as URIs
if the SQLITE_OPEN_URI flag is set when the database connection is
opened.
By default, URI handling is globally disabled.
The default value may be changed by compiling with the SQLITE_USE_URI
symbol defined.
.It SQLITE_CONFIG_COVERING_INDEX_SCAN This option takes a single integer
argument which is interpreted as a boolean in order to enable or disable
the use of covering indices for full table scans in the query optimizer.
The default setting is determined by the SQLITE_ALLOW_COVERING_INDEX_SCAN
compile-time option, or is "on" if that compile-time option is omitted.
The ability to disable the use of covering indices for full table scans
is because some incorrectly coded legacy applications might malfunction
when the optimization is enabled.
Providing the ability to disable the optimization allows the older,
buggy application code to work without change even with newer versions
of SQLite.
.It SQLITE_CONFIG_PCACHE and SQLITE_CONFIG_GETPCACHE These options are
obsolete and should not be used by new code.
They are retained for backwards compatibility but are now no-ops.
.It SQLITE_CONFIG_SQLLOG This option is only available if sqlite is compiled
with the SQLITE_ENABLE_SQLLOG pre-processor macro
defined.
The first argument should be a pointer to a function of type void(*)(void*,sqlite3*,const
char*, int).
The second should be of type (void*).
The callback is invoked by the library in three separate circumstances,
identified by the value passed as the fourth parameter.
If the fourth parameter is 0, then the database connection passed as
the second argument has just been opened.
The third argument points to a buffer containing the name of the main
database file.
If the fourth parameter is 1, then the SQL statement that the third
parameter points to has just been executed.
Or, if the fourth parameter is 2, then the connection being passed
as the second parameter is being closed.
The third parameter is passed NULL In this case.
An example of using this configuration option can be seen in the "test_sqllog.c"
source file in the canonical SQLite source tree.
.It SQLITE_CONFIG_MMAP_SIZE SQLITE_CONFIG_MMAP_SIZE takes two 64-bit integer
(sqlite3_int64) values that are the default mmap size limit (the default
setting for PRAGMA mmap_size) and the maximum allowed
mmap size limit.
The default setting can be overridden by each database connection using
either the PRAGMA mmap_size command, or by using the
SQLITE_FCNTL_MMAP_SIZE file control.
The maximum allowed mmap size cannot be changed at run-time.
Nor may the maximum allowed mmap size exceed the compile-time maximum
mmap size set by the SQLITE_MAX_MMAP_SIZE compile-time
option.
If either argument to this option is negative, then that argument is
changed to its compile-time default.
.It SQLITE_CONFIG_WIN32_HEAPSIZE This option is only available if SQLite
is compiled for Windows with the SQLITE_WIN32_MALLOC
pre-processor macro defined.
SQLITE_CONFIG_WIN32_HEAPSIZE takes a 32-bit unsigned integer value
that specifies the maximum size of the created heap.
.El
.Pp
.Sh SEE ALSO
.Xr sqlite3 3 ,
.Xr SQLITE_OK 3 ,
.Xr SQLITE_IOERR_READ 3 ,
.Xr sqlite3_stmt 3 ,
.Xr SQLITE_OK 3 ,
.Xr sqlite3_config 3 ,
.Xr sqlite3_db_config 3 ,
.Xr sqlite3_log 3 ,
.Xr sqlite3_malloc 3 ,
.Xr sqlite3_mem_methods 3 ,
.Xr sqlite3_memory_used 3 ,
.Xr sqlite3_mutex_methods 3 ,
.Xr sqlite3_open 3 ,
.Xr sqlite3_pcache_methods2 3 ,
.Xr sqlite3_mprintf 3 ,
.Xr sqlite3_soft_heap_limit64 3 ,
.Xr sqlite3_status 3 ,
.Xr SQLITE_CONFIG_SINGLETHREAD 3 ,
.Xr SQLITE_DBCONFIG_LOOKASIDE 3 ,
.Xr SQLITE_OK 3 ,
.Xr SQLITE_FCNTL_LOCKSTATE 3 ,
.Xr SQLITE_OPEN_READONLY 3