sqlite.h


Caché de página definido por la aplicación

typedef struct sqlite3_pcache_methods2 sqlite3_pcache_methods2;
struct sqlite3_pcache_methods2 {
  int iVersion;
  void *pArg;
  int (*xInit)(void*);
  void (*xShutdown)(void*);
  sqlite3_pcache *(*xCreate)(int szPage, int szExtra, int bPurgeable);
  void (*xCachesize)(sqlite3_pcache*, int nCachesize);
  int (*xPagecount)(sqlite3_pcache*);
  sqlite3_pcache_page *(*xFetch)(sqlite3_pcache*, unsigned key, int createFlag);
  void (*xUnpin)(sqlite3_pcache*, sqlite3_pcache_page*, int discard);
  void (*xRekey)(sqlite3_pcache*, sqlite3_pcache_page*, 
      unsigned oldKey, unsigned newKey);
  void (*xTruncate)(sqlite3_pcache*, unsigned iLimit);
  void (*xDestroy)(sqlite3_pcache*);
  void (*xShrink)(sqlite3_pcache*);
};

El interfaz sqlite3_config(SQLITE_CONFIG_PCACHE2, ...) puede registrar una implementación de caché de página alternativo pasando una instancia de la estructura sqlite3_pcache_methods2. En muchas aplicaciones, la mayor parte de la memoria del montón asignada por SQLite se usa para el caché de página. Mediante la implementación de un caché de página personalizado usando esta función, una aplicación puede controlar mejor la cantidad de memoria consumida por SQLite, el modo en que esa memoria es asignada y liberada, y las políticas usadas para determinar exactametne que partes del fichero de la base de datos son cacheadas y por cuanto tiempo.

El mecanismo de caché de página alternativo es una medida extrema que sólo es necesaria para las aplicaciones más exigentes. La caché de página integrada es la recomendada para la mayoría de las aplicaciones.

El contenido de la estructura sqlite3_pcache_methods2 se copia en un buffer interno por SQLite dentro de la llamada a sqlite3_config. De modo que la aplicación puede descartar el parámetro después de que la llamada a sqlite3_config() regrese.

El método xInit() es llamado una vez para cada llamada efectiva a sqlite3_initialize() (normalmente sólo una durante el tiempo de vida del proceso). Al método xInit() se lo pasa una copia del valor sqlite3_pcache_methods2.pArg. La intención del método xInit() es la creación de las estructuras de datos globales necesarias para la implementación de la caché de página personalizada. Si el método xInit() es NULL, se usará la caché de página por defecto integrada en lugar de la definida por la aplicación.

EL método xShutdown() es invocado por sqlite3_shutdown(). Puede ser usado para limpiar cualquier recurso externo antes de apagar el proceso, si es necesario. El método xShutdown() puede ser NULL.

SQLite serializa automáticamente las llamadas al método xInit, de modo que ese método no necesita ser multihilo. El método xShutdown sólo es llamado desde sqlite3_shutdown() asi que no necesita ser multihilo tampoco. Todos los otros métodos deben ser multihilo en aplicaciones multihilo.

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

SQLite invoca al método xCreate() para construir una nueva instancia de caché. Típicamente, SQLite creará una instancia de caché para cada fichero de base de datos abierta, aunque esto no está garantizado. El primer parámetro, szPage, es el tamaño en bytes de las páginas que deben ser asignadas por la caché. szPage será siempre una potencia de dos. El segundo parámetro szExtra es un número de bytes de almacenamiento extra asociado con cada entrada en la caché de página. El parámetro szExtra será un número menor de 250. SQLite usará los bytes szExtra en cada página para almacenar metadatos sobre la página de base de datos subyacente en disco. El valor pasado en szExtra depende de la versión de SQLite, la plataforma objetivo, y como haya sido compilado SQLite. El tercer argumento para xCreate(), bPurgeable, es true si la caché que está siendo creada será usada para cachear páginas de base de datos de un fichero almacenado en disco, o false si se usarña para una base de datos en memoria. La implementación de la caché no tiene que hacer nada especial en base al valor de bPurgeable; es sólo consultivo. En una caché donde bPurgeable es false, SQLite nunca invocará xUnpin() excepto para borrar deliberadamente una página. En otras palabras, las llamadas a xUnpin() en una caché con bPurgeable puesto a false siempre dentrán la bandera "descartar" a true. Por lo tanto, una caché creada con bPurgeable false nunca contendrá ninguna página liberada.

El método xCachesize() puede ser llamado en cualquier momento por SQLite para asignar el cache-size máximo sugerido (número de páginas que almacena) de la instancia de la caché pasado como el primer argumento. Este es el valor configurado usando el comando de SQLite "PRAGMA cache_size". Igual que con el parámetro bPurgeable, la implementación no tiene por qué hacer nada con este valor, es sólo consultivo.

El método xPagecount() debe retornar el número de páginas actualmente almacenadas en la caché, tanto usadas como liberadas.

El método xFetch() localiza una página en la caché y devuelve un puntero a un objeto sqlite3_pcache_page asociado con esa página, o un puntero NULL. El elemento pBuf del objeto sqlite3_pcache_page devuelto será un puntero a un buffer de szPage bytes usado para almacenar el contenido de una única página de base de datos. El elemento pExtra de sqlite3_pcache_page será un puntero a los szExtra bytes de almacenamiento extra que SQLite ha solicitado para cada entrada en la caché de páginas.

La página a descargar se determina mediante la key. El valor mínimo para key es 1. Después de ser recuperada usando xFetch, la página se considera "clavada" (pinned).

Si la página requerida ya está en la caché de páginas, entonces la implementación de la caché debe retornar un puntero al buffer de página con su contenido intacto. Si la página requerida no está todavía en la caché, entonces la implementación de la caché debe usar el valor del parámetro createFlag para ayudar a determinar qué acción tomar:

createFlagComportamiento cuando la página no está ya en la caché
0No asignar una nueva página. Retornar NULL.
1Asignar una nueva página si es fácil y conveniente hacerlo. En caso contrario retornar NULL.
2Hacer cualquier esfuerzo para asignar una nueva página. Sólo se retorna NULL si asignar una nueva página es realmente imposible.

SQLite normalmente invocará a xFetch() con un createFlag de 0 ó 1. SQLite sólo usará un valor 2 para createFlag después de una llamada previa con un valor 1 que haya fallado. Entre las llamadas a xFetch(), SQLite puede intentar liberar una o más páginas de caché mediante el volcado del contenido de esas páginas en disco y la sincronización de la caché de disco del sistema operativo.

xUnpin() es llamado por SQLite cin un puntero a una página actualmente anclada como segundo argumento. Si el tercer parámetro, discart, es no nulo, entonces la página debe ser expulsada de la caché. Si el parámetro discard es cero, entonces la página puede ser descartada o retenida a discrección de la implementación de la caché de página. La implementación de la caché de página puede elegir expulsar páginas no ancladas en cualquier momento.

La caché no debe realizaqr nigún recuento de referencias. Una sencilla llamada a xUnpin() libera la página independientemente del número de llamadas previas a xFetch().

El método xRekey() se usa para cambiar el valor de key asociado con la página pasada como segundo argumento. Si la caché contenía previamente una entrada asociada con newKey, esta debe ser descartada. Se garantiza que cualquier entrada de caché previamente asociada con newKey no se ancló.

Cuando SQLite llama al método xTruncate(), la caché debe descartar todas las entradas de caché existentes cón números de página (keys) mayores o iguales que el valor del parámetro iLimit pasado a xTruncate(). Si cualquiera de esas páginas está anclada, serán desancladas implícitamente, lo que significa que podrán ser descartadas de forma segura.

El método xDestroy() se usa para borrar una caché asignada por xCreate(). Todos los recursos asociados con la caché espeficificada deben ser liberados. Después de llamar al método xDestroy(), SQLite considera que el manipulador sqlite3_pcache* es inválido, y no lo usará con ninguna otra función sqlite3_pcache_methods2.

SQLite invoca el método xShrink() cuando quiere que la caché de página libere tanta memoria del montón como sea posible. La implementación de la caché de página no está obligada a liberar ninguna memoria, pero implementaciones bien hechas deben hacerlo mejor.