1.Dd December 19, 2018 2.Dt SQLITE3_MEM_METHODS 3 3.Os 4.Sh NAME 5.Nm sqlite3_mem_methods , 6.Nm sqlite3_mem_methods 7.Nd Memory Allocation Routines 8.Sh SYNOPSIS 9.Vt typedef struct sqlite3_mem_methods sqlite3_mem_methods; 10.Vt struct sqlite3_mem_methods ; 11.Sh DESCRIPTION 12An instance of this object defines the interface between SQLite and 13low-level memory allocation routines. 14.Pp 15This object is used in only one place in the SQLite interface. 16A pointer to an instance of this object is the argument to sqlite3_config() 17when the configuration option is SQLITE_CONFIG_MALLOC 18or SQLITE_CONFIG_GETMALLOC. 19By creating an instance of this object and passing it to sqlite3_config(SQLITE_CONFIG_MALLOC) 20during configuration, an application can specify an alternative memory 21allocation subsystem for SQLite to use for all of its dynamic memory 22needs. 23.Pp 24Note that SQLite comes with several built-in memory allocators 25that are perfectly adequate for the overwhelming majority of applications 26and that this object is only useful to a tiny minority of applications 27with specialized memory allocation requirements. 28This object is also used during testing of SQLite in order to specify 29an alternative memory allocator that simulates memory out-of-memory 30conditions in order to verify that SQLite recovers gracefully from 31such conditions. 32.Pp 33The xMalloc, xRealloc, and xFree methods must work like the malloc(), 34realloc() and free() functions from the standard C library. 35SQLite guarantees that the second argument to xRealloc is always a 36value returned by a prior call to xRoundup. 37.Pp 38xSize should return the allocated size of a memory allocation previously 39obtained from xMalloc or xRealloc. 40The allocated size is always at least as big as the requested size 41but may be larger. 42.Pp 43The xRoundup method returns what would be the allocated size of a memory 44allocation given a particular requested size. 45Most memory allocators round up memory allocations at least to the 46next multiple of 8. 47Some allocators round up to a larger multiple or to a power of 2. 48Every memory allocation request coming in through sqlite3_malloc() 49or sqlite3_realloc() first calls xRoundup. 50If xRoundup returns 0, that causes the corresponding memory allocation 51to fail. 52.Pp 53The xInit method initializes the memory allocator. 54For example, it might allocate any require mutexes or initialize internal 55data structures. 56The xShutdown method is invoked (indirectly) by sqlite3_shutdown() 57and should deallocate any resources acquired by xInit. 58The pAppData pointer is used as the only parameter to xInit and xShutdown. 59.Pp 60SQLite holds the SQLITE_MUTEX_STATIC_MASTER 61mutex when it invokes the xInit method, so the xInit method need not 62be threadsafe. 63The xShutdown method is only called from sqlite3_shutdown() 64so it does not need to be threadsafe either. 65For all other methods, SQLite holds the SQLITE_MUTEX_STATIC_MEM 66mutex as long as the SQLITE_CONFIG_MEMSTATUS 67configuration option is turned on (which it is by default) and so the 68methods are automatically serialized. 69However, if SQLITE_CONFIG_MEMSTATUS is disabled, 70then the other methods must be threadsafe or else make their own arrangements 71for serialization. 72.Pp 73SQLite will never invoke xInit() more than once without an intervening 74call to xShutdown(). 75.Sh SEE ALSO 76.Xr sqlite3_config 3 , 77.Xr sqlite3_malloc 3 , 78.Xr sqlite3_initialize 3 , 79.Xr SQLITE_CONFIG_SINGLETHREAD 3 , 80.Xr SQLITE_MUTEX_FAST 3 81