NAME
sqlite3_mem_methods,
sqlite3_mem_methods
—
Memory Allocation Routines
SYNOPSIS
typedef struct sqlite3_mem_methods sqlite3_mem_methods;
struct sqlite3_mem_methods;
DESCRIPTION
An instance of this object defines the interface between SQLite and low-level
memory allocation routines.
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.
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.
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.
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.
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.
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.
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.
SQLite will never invoke xInit() more than once without an intervening call to
xShutdown().
SEE ALSO
sqlite3_config(3),
sqlite3_malloc(3),
sqlite3_initialize(3),
SQLITE_CONFIG_SINGLETHREAD(3),
SQLITE_MUTEX_FAST(3)