Updated: 2022/Sep/29

Please read Privacy Policy. It's for your privacy.

SQLITE3_MEM_METHODS(3)     Library Functions Manual     SQLITE3_MEM_METHODS(3)

NAME
     sqlite3_mem_methods, sqlite3_mem_methods - memory allocation routines

SYNOPSIS
     #include <sqlite3.h>

     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 required 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_MAIN 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().

IMPLEMENTATION NOTES
     These declarations were extracted from the interface documentation at
     line 1702.

     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() */
     };

SEE ALSO
     sqlite3_config(3), sqlite3_initialize(3), sqlite3_malloc(3),
     SQLITE_CONFIG_SINGLETHREAD(3), SQLITE_MUTEX_FAST(3)

NetBSD 10.99                    August 24, 2023                   NetBSD 10.99