1.Dd January 24, 2024 2.Dt SQLITE3_MUTEX_METHODS 3 3.Os 4.Sh NAME 5.Nm sqlite3_mutex_methods , 6.Nm sqlite3_mutex_methods 7.Nd mutex methods object 8.Sh SYNOPSIS 9.In sqlite3.h 10.Vt typedef struct sqlite3_mutex_methods sqlite3_mutex_methods; 11.Vt struct sqlite3_mutex_methods ; 12.Sh DESCRIPTION 13An instance of this structure defines the low-level routines used to 14allocate and use mutexes. 15.Pp 16Usually, the default mutex implementations provided by SQLite are sufficient, 17however the application has the option of substituting a custom implementation 18for specialized deployments or systems for which SQLite does not provide 19a suitable implementation. 20In this case, the application creates and populates an instance of 21this structure to pass to sqlite3_config() along with the SQLITE_CONFIG_MUTEX 22option. 23Additionally, an instance of this structure can be used as an output 24variable when querying the system for the current mutex implementation, 25using the SQLITE_CONFIG_GETMUTEX option. 26.Pp 27The xMutexInit method defined by this structure is invoked as part 28of system initialization by the sqlite3_initialize() function. 29The xMutexInit routine is called by SQLite exactly once for each effective 30call to 31.Fn sqlite3_initialize . 32The xMutexEnd method defined by this structure is invoked as part of 33system shutdown by the sqlite3_shutdown() function. 34The implementation of this method is expected to release all outstanding 35resources obtained by the mutex methods implementation, especially 36those obtained by the xMutexInit method. 37The xMutexEnd() interface is invoked exactly once for each call to 38.Fn sqlite3_shutdown . 39The remaining seven methods defined by this structure (xMutexAlloc, 40xMutexFree, xMutexEnter, xMutexTry, xMutexLeave, xMutexHeld and xMutexNotheld) 41implement the following interfaces (respectively): 42.Bl -bullet 43.It 44.Fn sqlite3_mutex_alloc 45.It 46.Fn sqlite3_mutex_free 47.It 48.Fn sqlite3_mutex_enter 49.It 50.Fn sqlite3_mutex_try 51.It 52.Fn sqlite3_mutex_leave 53.It 54.Fn sqlite3_mutex_held 55.It 56.Fn sqlite3_mutex_notheld 57.El 58.Pp 59The only difference is that the public sqlite3_XXX functions enumerated 60above silently ignore any invocations that pass a NULL pointer instead 61of a valid mutex handle. 62The implementations of the methods defined by this structure are not 63required to handle this case. 64The results of passing a NULL pointer instead of a valid mutex handle 65are undefined (i.e. it is acceptable to provide an implementation that 66segfaults if it is passed a NULL pointer). 67.Pp 68The xMutexInit() method must be threadsafe. 69It must be harmless to invoke xMutexInit() multiple times within the 70same process and without intervening calls to xMutexEnd(). 71Second and subsequent calls to xMutexInit() must be no-ops. 72.Pp 73xMutexInit() must not use SQLite memory allocation ( 74.Fn sqlite3_malloc 75and its associates). 76Similarly, xMutexAlloc() must not use SQLite memory allocation for 77a static mutex. 78However xMutexAlloc() may use SQLite memory allocation for a fast or 79recursive mutex. 80.Pp 81SQLite will invoke the xMutexEnd() method when 82.Fn sqlite3_shutdown 83is called, but only if the prior call to xMutexInit returned SQLITE_OK. 84If xMutexInit fails in any way, it is expected to clean up after itself 85prior to returning. 86.Sh IMPLEMENTATION NOTES 87These declarations were extracted from the 88interface documentation at line 8066. 89.Bd -literal 90typedef struct sqlite3_mutex_methods sqlite3_mutex_methods; 91struct sqlite3_mutex_methods { 92 int (*xMutexInit)(void); 93 int (*xMutexEnd)(void); 94 sqlite3_mutex *(*xMutexAlloc)(int); 95 void (*xMutexFree)(sqlite3_mutex *); 96 void (*xMutexEnter)(sqlite3_mutex *); 97 int (*xMutexTry)(sqlite3_mutex *); 98 void (*xMutexLeave)(sqlite3_mutex *); 99 int (*xMutexHeld)(sqlite3_mutex *); 100 int (*xMutexNotheld)(sqlite3_mutex *); 101}; 102.Ed 103.Sh SEE ALSO 104.Xr sqlite3_initialize 3 , 105.Xr sqlite3_malloc 3 , 106.Xr sqlite3_mutex_alloc 3 , 107.Xr sqlite3_mutex_held 3 , 108.Xr SQLITE_CONFIG_SINGLETHREAD 3 109