Updated: 2022/Sep/29

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


SQLITE3_MUTEX_METHODS(3)   Library Functions Manual   SQLITE3_MUTEX_METHODS(3)

NAME
     sqlite3_mutex_methods, sqlite3_mutex_methods - mutex methods object

SYNOPSIS
     #include <sqlite3.h>

     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.

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

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

SEE ALSO
     sqlite3_initialize(3), sqlite3_malloc(3), sqlite3_mutex_alloc(3),
     sqlite3_mutex_held(3), SQLITE_CONFIG_SINGLETHREAD(3)

NetBSD 10.99                    August 24, 2023                   NetBSD 10.99