Rutinas de reserva de memoria

typedef struct sqlite3_mem_methods sqlite3_mem_methods;
struct sqlite3_mem_methods {
  void *(*xMalloc)(int);         /* Función de reserva de memoria */
  void (*xFree)(void*);          /* Liberar una reserva previa */
  void *(*xRealloc)(void*,int);  /* Redimensionar una reserva */
  int (*xSize)(void*);           /* Devolver el tamaño de una reserva */
  int (*xRoundup)(int);          /* Redondear hacia arriba el tamaño requerido para una reserva */
  int (*xInit)(void*);           /* Inicializar el asignador de memoria */
  void (*xShutdown)(void*);      /* Liberar el asignador de memoria */
  void *pAppData;                /* Argumento para xInit() y xShutdown() */
};

Una instancia de este objeto define el interfaz entre SQLite y las rutinas de asignación de memoria de bajo nivel.

Este objeto se usa sólo en un sitio en el interfaz SQLite. Un puntero a una instancia de este objeto es el argumento para sqlite3_config() cuando la opción de configuración es SQLITE_CONFIG_MALLOC o SQLITE_CONFIG_GETMALLOC. Mediante la creación de una instancia de este objeto y pasándolo a sqlite3_config(SQLITE_CONFIG_MALLOC) durante la configuración, una aplicación puede especificar un subsistema de asignación de memoria alternativo para SQLite para usarse con todas las necesidades de memoria dinámica.

Hay que tener en cuenta que SQLite viene con varios asignadores de memoria incluidos que son perfectamente adecuados para la inmensa mayoría de las aplicaciones y que este objeto sólo es útil para una pequeña minoría de aplicaciones con requerimientos de asignación de memoria especializados. Este objeto se usa también durante pruebas de SQLite con el fin de especificar un asignador de memoria alternativo que simule condiciones de falta de memoria con el objetivo de verificar si SQLite se recupera sin problemas de esas condiciones.

Los métodos xMalloc, xRealloc y xFree deben trabajar como las funciones malloc(), realloc() y free() de la biblioteca estándar C. SQLite garantiza que el segundo argumento para xRealloc es siempre un valor retornado por una llamada previa a xRoundup.

xSize debe retornar el tamaño asignado de una asignación de memoria previamente obtenida desde xMalloc o xRealloc. El tamaño asignado es siempre al menos tan grande como el tamaño requerido pero puede ser mayor.

El método xRoundup devuelve el tamaño que sería asignado a una asignación, dado un tamaño de una petición en particular. La mayoría de las asignaciones de memoria redondean hacia arriba la asignación de memoria al menos al siguiente múltiplo de 8. Ciertas asignaciones redondean hacia arriba a un múltiplo mayor o a una potencia de 2. Cada petición de asignación de memoria que se lleve a cabo a través de sqlite3_malloc() o sqlite3_realloc() primero llama a xRoundup. Si xRoundup devuelve 0, esto provoca que la asignación de memoria correspondiente falle.

El método xInit inicializa el asignador de memoria. (Por ejemplo, debe asignar cualquier mutex necesario o inicializar estructuras de datos internas). El método xShutdown es invocado (indirectamente) por sqlite3_shutdown() y debe liberar cualquier recurso adquirido por xInit. El puntero pAppData se usa como el único parámetro para xInit y xShutdown.

SQLite mantienen el mutex SQLITE_MUTEX_STATIC_MASTER cuando invoca el método xInit, de modo que el método xInit no necesita ser multihilo. El método xShutdown sólo es invocado desde sqlite3_initialize() así que tampoco necesita ser multihilo. Para todos los otros métodos, SQLite mantiene el mutex SQLITE_MUTEX_STATIC_MEM siempre y cuando la opción de configuración SQLITE_CONFIG_MEMSTATUS este activa (que lo es por defecto) y así, los métodos son serializados automáticamente. Sin embargo, si se desactiva SQLITE_CONFIG_MEMSTATUS, los otros métodos deben ser multihilo o bien hacer sus porpios métodos para la serialización.

SQLite nunca invoca a xInit() más de una vez sin una llamada a xShutdown().