1.Dd January 24, 2024 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.In sqlite3.h 10.Vt typedef struct sqlite3_mem_methods sqlite3_mem_methods; 11.Vt struct sqlite3_mem_methods ; 12.Sh DESCRIPTION 13An instance of this object defines the interface between SQLite and 14low-level memory allocation routines. 15.Pp 16This object is used in only one place in the SQLite interface. 17A pointer to an instance of this object is the argument to 18.Fn sqlite3_config 19when the configuration option is SQLITE_CONFIG_MALLOC 20or SQLITE_CONFIG_GETMALLOC. 21By creating an instance of this object and passing it to sqlite3_config(SQLITE_CONFIG_MALLOC) 22during configuration, an application can specify an alternative memory 23allocation subsystem for SQLite to use for all of its dynamic memory 24needs. 25.Pp 26Note that SQLite comes with several built-in memory allocators 27that are perfectly adequate for the overwhelming majority of applications 28and that this object is only useful to a tiny minority of applications 29with specialized memory allocation requirements. 30This object is also used during testing of SQLite in order to specify 31an alternative memory allocator that simulates memory out-of-memory 32conditions in order to verify that SQLite recovers gracefully from 33such conditions. 34.Pp 35The xMalloc, xRealloc, and xFree methods must work like the malloc(), 36realloc() and free() functions from the standard C library. 37SQLite guarantees that the second argument to xRealloc is always a 38value returned by a prior call to xRoundup. 39.Pp 40xSize should return the allocated size of a memory allocation previously 41obtained from xMalloc or xRealloc. 42The allocated size is always at least as big as the requested size 43but may be larger. 44.Pp 45The xRoundup method returns what would be the allocated size of a memory 46allocation given a particular requested size. 47Most memory allocators round up memory allocations at least to the 48next multiple of 8. 49Some allocators round up to a larger multiple or to a power of 2. 50Every memory allocation request coming in through 51.Fn sqlite3_malloc 52or 53.Fn sqlite3_realloc 54first calls xRoundup. 55If xRoundup returns 0, that causes the corresponding memory allocation 56to fail. 57.Pp 58The xInit method initializes the memory allocator. 59For example, it might allocate any required mutexes or initialize internal 60data structures. 61The xShutdown method is invoked (indirectly) by 62.Fn sqlite3_shutdown 63and should deallocate any resources acquired by xInit. 64The pAppData pointer is used as the only parameter to xInit and xShutdown. 65.Pp 66SQLite holds the SQLITE_MUTEX_STATIC_MAIN mutex 67when it invokes the xInit method, so the xInit method need not be threadsafe. 68The xShutdown method is only called from 69.Fn sqlite3_shutdown 70so it does not need to be threadsafe either. 71For all other methods, SQLite holds the SQLITE_MUTEX_STATIC_MEM 72mutex as long as the SQLITE_CONFIG_MEMSTATUS 73configuration option is turned on (which it is by default) and so the 74methods are automatically serialized. 75However, if SQLITE_CONFIG_MEMSTATUS is disabled, 76then the other methods must be threadsafe or else make their own arrangements 77for serialization. 78.Pp 79SQLite will never invoke xInit() more than once without an intervening 80call to xShutdown(). 81.Sh IMPLEMENTATION NOTES 82These declarations were extracted from the 83interface documentation at line 1702. 84.Bd -literal 85typedef struct sqlite3_mem_methods sqlite3_mem_methods; 86struct sqlite3_mem_methods { 87 void *(*xMalloc)(int); /* Memory allocation function */ 88 void (*xFree)(void*); /* Free a prior allocation */ 89 void *(*xRealloc)(void*,int); /* Resize an allocation */ 90 int (*xSize)(void*); /* Return the size of an allocation */ 91 int (*xRoundup)(int); /* Round up request size to allocation size */ 92 int (*xInit)(void*); /* Initialize the memory allocator */ 93 void (*xShutdown)(void*); /* Deinitialize the memory allocator */ 94 void *pAppData; /* Argument to xInit() and xShutdown() */ 95}; 96.Ed 97.Sh SEE ALSO 98.Xr sqlite3_config 3 , 99.Xr sqlite3_initialize 3 , 100.Xr sqlite3_malloc 3 , 101.Xr SQLITE_CONFIG_SINGLETHREAD 3 , 102.Xr SQLITE_MUTEX_FAST 3 103