diff options
Diffstat (limited to 'static/netbsd/man3/sqlite3_mem_methods.3')
| -rw-r--r-- | static/netbsd/man3/sqlite3_mem_methods.3 | 102 |
1 files changed, 102 insertions, 0 deletions
diff --git a/static/netbsd/man3/sqlite3_mem_methods.3 b/static/netbsd/man3/sqlite3_mem_methods.3 new file mode 100644 index 00000000..a18d4b46 --- /dev/null +++ b/static/netbsd/man3/sqlite3_mem_methods.3 @@ -0,0 +1,102 @@ +.Dd January 24, 2024 +.Dt SQLITE3_MEM_METHODS 3 +.Os +.Sh NAME +.Nm sqlite3_mem_methods , +.Nm sqlite3_mem_methods +.Nd memory allocation routines +.Sh SYNOPSIS +.In sqlite3.h +.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 +.Fn 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 +.Fn sqlite3_malloc +or +.Fn 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 required mutexes or initialize internal +data structures. +The xShutdown method is invoked (indirectly) by +.Fn 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_MAIN mutex +when it invokes the xInit method, so the xInit method need not be threadsafe. +The xShutdown method is only called from +.Fn 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 IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 1702. +.Bd -literal +typedef struct sqlite3_mem_methods sqlite3_mem_methods; +struct sqlite3_mem_methods { + void *(*xMalloc)(int); /* Memory allocation function */ + void (*xFree)(void*); /* Free a prior allocation */ + void *(*xRealloc)(void*,int); /* Resize an allocation */ + int (*xSize)(void*); /* Return the size of an allocation */ + int (*xRoundup)(int); /* Round up request size to allocation size */ + int (*xInit)(void*); /* Initialize the memory allocator */ + void (*xShutdown)(void*); /* Deinitialize the memory allocator */ + void *pAppData; /* Argument to xInit() and xShutdown() */ +}; +.Ed +.Sh SEE ALSO +.Xr sqlite3_config 3 , +.Xr sqlite3_initialize 3 , +.Xr sqlite3_malloc 3 , +.Xr SQLITE_CONFIG_SINGLETHREAD 3 , +.Xr SQLITE_MUTEX_FAST 3 |