81 lines
3.3 KiB
Groff
81 lines
3.3 KiB
Groff
.Dd December 18, 2016
|
|
.Dt SQLITE3_MEM_METHODS 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm sqlite3_mem_methods ,
|
|
.Nm sqlite3_mem_methods
|
|
.Nd Memory Allocation Routines
|
|
.Sh SYNOPSIS
|
|
.Vt typedef struct sqlite3_mem_methods sqlite3_mem_methods;
|
|
.Vt struct sqlite3_mem_methods ;
|
|
.Sh DESCRIPTION
|
|
An instance of this object defines the interface between SQLite and
|
|
low-level memory allocation routines.
|
|
.Pp
|
|
This object is used in only one place in the SQLite interface.
|
|
A pointer to an instance of this object is the argument to sqlite3_config()
|
|
when the configuration option is SQLITE_CONFIG_MALLOC
|
|
or SQLITE_CONFIG_GETMALLOC.
|
|
By creating an instance of this object and passing it to sqlite3_config(SQLITE_CONFIG_MALLOC)
|
|
during configuration, an application can specify an alternative memory
|
|
allocation subsystem for SQLite to use for all of its dynamic memory
|
|
needs.
|
|
.Pp
|
|
Note that SQLite comes with several built-in memory allocators
|
|
that are perfectly adequate for the overwhelming majority of applications
|
|
and that this object is only useful to a tiny minority of applications
|
|
with specialized memory allocation requirements.
|
|
This object is also used during testing of SQLite in order to specify
|
|
an alternative memory allocator that simulates memory out-of-memory
|
|
conditions in order to verify that SQLite recovers gracefully from
|
|
such conditions.
|
|
.Pp
|
|
The xMalloc, xRealloc, and xFree methods must work like the malloc(),
|
|
realloc() and free() functions from the standard C library.
|
|
SQLite guarantees that the second argument to xRealloc is always a
|
|
value returned by a prior call to xRoundup.
|
|
.Pp
|
|
xSize should return the allocated size of a memory allocation previously
|
|
obtained from xMalloc or xRealloc.
|
|
The allocated size is always at least as big as the requested size
|
|
but may be larger.
|
|
.Pp
|
|
The xRoundup method returns what would be the allocated size of a memory
|
|
allocation given a particular requested size.
|
|
Most memory allocators round up memory allocations at least to the
|
|
next multiple of 8.
|
|
Some allocators round up to a larger multiple or to a power of 2.
|
|
Every memory allocation request coming in through sqlite3_malloc()
|
|
or sqlite3_realloc() first calls xRoundup.
|
|
If xRoundup returns 0, that causes the corresponding memory allocation
|
|
to fail.
|
|
.Pp
|
|
The xInit method initializes the memory allocator.
|
|
For example, it might allocate any require mutexes or initialize internal
|
|
data structures.
|
|
The xShutdown method is invoked (indirectly) by sqlite3_shutdown()
|
|
and should deallocate any resources acquired by xInit.
|
|
The pAppData pointer is used as the only parameter to xInit and xShutdown.
|
|
.Pp
|
|
SQLite holds the SQLITE_MUTEX_STATIC_MASTER
|
|
mutex when it invokes the xInit method, so the xInit method need not
|
|
be threadsafe.
|
|
The xShutdown method is only called from sqlite3_shutdown()
|
|
so it does not need to be threadsafe either.
|
|
For all other methods, SQLite holds the SQLITE_MUTEX_STATIC_MEM
|
|
mutex as long as the SQLITE_CONFIG_MEMSTATUS
|
|
configuration option is turned on (which it is by default) and so the
|
|
methods are automatically serialized.
|
|
However, if SQLITE_CONFIG_MEMSTATUS is disabled,
|
|
then the other methods must be threadsafe or else make their own arrangements
|
|
for serialization.
|
|
.Pp
|
|
SQLite will never invoke xInit() more than once without an intervening
|
|
call to xShutdown().
|
|
.Sh SEE ALSO
|
|
.Xr sqlite3_config 3 ,
|
|
.Xr sqlite3_malloc 3 ,
|
|
.Xr sqlite3_initialize 3 ,
|
|
.Xr SQLITE_CONFIG_SINGLETHREAD 3 ,
|
|
.Xr SQLITE_MUTEX_FAST 3
|