sqlite.h


Manipulación de mutex

typedef struct sqlite3_mutex_methods sqlite3_mutex_methods;
struct sqlite3_mutex_methods {
  int (*xMutexInit)(void);
  int (*xMutexEnd)(void);
  sqlite3_mutex *(*xMutexAlloc)(int);
  void (*xMutexFree)(sqlite3_mutex *);
  void (*xMutexEnter)(sqlite3_mutex *);
  int (*xMutexTry)(sqlite3_mutex *);
  void (*xMutexLeave)(sqlite3_mutex *);
  int (*xMutexHeld)(sqlite3_mutex *);
  int (*xMutexNotheld)(sqlite3_mutex *);
};

Una instancia de esta estructura define las rutinas de bajo nivel usadas para asignar y usar mutexes.

Por lo general, las implementaciones por defecto proporcionadas por SQLite son suficientes, sin embargo el usuario tiene la opción de sustituirlas por implementaciones a medida para implementaciones especializadas o sistemas para los que SQLite no proporciona una implementación adecuada. En ese caso, el usuario crea y rellena una instancia de esta estructura para pasarla a sqlite3_config() junto con la opción SQLITE_CONFIG_MUTEX. Adicionalmente, una instancia de esta estructura puede ser usada como una variable de salida cuando se consulta el sistema para la implementación actual del mutex, usando la opción SQLITE_CONFIG_GETMUTEX.

El método xMutexInit definido por esta estructura es invocado como parte del sistema de inicialización por la función sqlite3_initialize(). La rutina xMutexInit es llamada por SQLite exactamente una vez por cada llamada efectiva a sqlite3_initialize().

El método xMutexEnd definido por esta estructura es invocado como parte del apagado del sistema por la función sqlite3_shutdown(). La implementación de este método debe liberar todos los recursos externos obtenidos por la implementación de los métodos de mutex, especialmente aquellos obtenidos por el método xMutexInit. El interfaz xMutexEnd() es invocado una vez por cada llamada a sqlite3_shutdown().

Los siete métodos restantes definidos por esta estructura (xMutexAlloc, xMutexFree, xMutexEnter, xMutexTry, xMutexLeave, xMutexHeld y xMutexNotheld) implementan los interfaces siguientes, respectivamente:

La única diferencia es que estas funciones públicas sqlite3_xxx enumeradas antes ignoran cualquier invocación que pase un puntero NULL en lugar de un manipulador de mutex válido. La implementación de los métodos definidos por esta estructura no requieren manipular este caso, el resultado de pasar un puntero NULL en lugar de un manipulador de mutex válido es indefinido (es decir, es aceptable proporcionar una implementación que falle si se pasa un puntero NULL).

El método xMutexInit() debe ser multihilo. Debe ser inofensivo invocar varias veces a xMutexInit() en el mismo proceso y sin intervención de llamadas a xMutexEnd(). La segunda y siguientes llamadas a xMutexInit() no deben hacer nada.

xMutexInit() no debe usar asignación de memoria SQLite (sqlite3_malloc() y asociadas). De forma similar, xMutexAlloc() no debe usar asignación de memoria SQLite para un mutex estático. Sin embargo xMutexAlloc() puede usar asignación de memoria SQLite para un mutex rápido o recursivo.

SQLite invocará el método xMutexEnd() cuando se llame a sqlite3_shutdown(), pero sólo si la llamada previa a xMutexInit retorna SQLITE_OK. Si xMutexInit falla de cualquier forma, está previsto limpiar después, antes de que la función regrese.