NAME
sqlite3_mutex_methods,
sqlite3_mutex_methods
—
Mutex Methods Object
SYNOPSIS
typedef struct sqlite3_mutex_methods
sqlite3_mutex_methods;
struct sqlite3_mutex_methods;
DESCRIPTION
An instance of this structure defines the low-level routines used to allocate
and use mutexes.
Usually, the default mutex implementations provided by SQLite are sufficient,
however the application has the option of substituting a custom implementation
for specialized deployments or systems for which SQLite does not provide a
suitable implementation. In this case, the application creates and populates
an instance of this structure to pass to sqlite3_config() along with the
SQLITE_CONFIG_MUTEX option. Additionally, an instance of this structure can be
used as an output variable when querying the system for the current mutex
implementation, using the SQLITE_CONFIG_GETMUTEX option.
The xMutexInit method defined by this structure is invoked as part of system
initialization by the sqlite3_initialize() function. The xMutexInit routine is
called by SQLite exactly once for each effective call to sqlite3_initialize().
The xMutexEnd method defined by this structure is invoked as part of system
shutdown by the sqlite3_shutdown() function. The implementation of this method
is expected to release all outstanding resources obtained by the mutex methods
implementation, especially those obtained by the xMutexInit method. The
xMutexEnd() interface is invoked exactly once for each call to
sqlite3_shutdown().
The remaining seven methods defined by this structure (xMutexAlloc, xMutexFree,
xMutexEnter, xMutexTry, xMutexLeave, xMutexHeld and xMutexNotheld) implement
the following interfaces (respectively):
- sqlite3_mutex_alloc()
- sqlite3_mutex_free()
- sqlite3_mutex_enter()
- sqlite3_mutex_try()
- sqlite3_mutex_leave()
- sqlite3_mutex_held()
- sqlite3_mutex_notheld()
The only difference is that the public sqlite3_XXX functions enumerated above
silently ignore any invocations that pass a NULL pointer instead of a valid
mutex handle. The implementations of the methods defined by this structure are
not required to handle this case, the results of passing a NULL pointer
instead of a valid mutex handle are undefined (i.e. it is acceptable to
provide an implementation that segfaults if it is passed a NULL pointer).
The xMutexInit() method must be threadsafe. It must be harmless to invoke
xMutexInit() multiple times within the same process and without intervening
calls to xMutexEnd(). Second and subsequent calls to xMutexInit() must be
no-ops.
xMutexInit() must not use SQLite memory allocation (sqlite3_malloc() and its
associates). Similarly, xMutexAlloc() must not use SQLite memory allocation
for a static mutex. However xMutexAlloc() may use SQLite memory allocation for
a fast or recursive mutex.
SQLite will invoke the xMutexEnd() method when sqlite3_shutdown() is called, but
only if the prior call to xMutexInit returned SQLITE_OK. If xMutexInit fails
in any way, it is expected to clean up after itself prior to returning.
SEE ALSO
sqlite3_initialize(3),
sqlite3_malloc(3),
sqlite3_mutex_alloc(3),
sqlite3_mutex_held(3),
sqlite3_mutex_alloc(3),
sqlite3_mutex_held(3),
sqlite3_mutex_alloc(3),
sqlite3_initialize(3),
SQLITE_CONFIG_SINGLETHREAD(3)