1.Dd December 19, 2018 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.Vt typedef struct sqlite3_mutex_methods sqlite3_mutex_methods; 10.Vt struct sqlite3_mutex_methods ; 11.Sh DESCRIPTION 12An instance of this structure defines the low-level routines used to 13allocate and use mutexes. 14.Pp 15Usually, the default mutex implementations provided by SQLite are sufficient, 16however the application has the option of substituting a custom implementation 17for specialized deployments or systems for which SQLite does not provide 18a suitable implementation. 19In this case, the application creates and populates an instance of 20this structure to pass to sqlite3_config() along with the SQLITE_CONFIG_MUTEX 21option. 22Additionally, an instance of this structure can be used as an output 23variable when querying the system for the current mutex implementation, 24using the SQLITE_CONFIG_GETMUTEX option. 25.Pp 26The xMutexInit method defined by this structure is invoked as part 27of system initialization by the sqlite3_initialize() function. 28The xMutexInit routine is called by SQLite exactly once for each effective 29call to sqlite3_initialize(). 30.Pp 31The xMutexEnd method defined by this structure is invoked as part of 32system shutdown by the sqlite3_shutdown() function. 33The implementation of this method is expected to release all outstanding 34resources obtained by the mutex methods implementation, especially 35those obtained by the xMutexInit method. 36The xMutexEnd() interface is invoked exactly once for each call to 37sqlite3_shutdown(). 38.Pp 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 44sqlite3_mutex_alloc() 45.It 46sqlite3_mutex_free() 47.It 48sqlite3_mutex_enter() 49.It 50sqlite3_mutex_try() 51.It 52sqlite3_mutex_leave() 53.It 54sqlite3_mutex_held() 55.It 56sqlite3_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, the results of passing a NULL pointer 64instead of a valid mutex handle are undefined (i.e. 65it is acceptable to provide an implementation that segfaults if it 66is 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 (sqlite3_malloc() 74and its associates). 75Similarly, xMutexAlloc() must not use SQLite memory allocation for 76a static mutex. 77However xMutexAlloc() may use SQLite memory allocation for a fast or 78recursive mutex. 79.Pp 80SQLite will invoke the xMutexEnd() method when sqlite3_shutdown() 81is called, but only if the prior call to xMutexInit returned SQLITE_OK. 82If xMutexInit fails in any way, it is expected to clean up after itself 83prior to returning. 84.Sh SEE ALSO 85.Xr sqlite3_initialize 3 , 86.Xr sqlite3_malloc 3 , 87.Xr sqlite3_mutex_alloc 3 , 88.Xr sqlite3_mutex_held 3 , 89.Xr sqlite3_mutex_alloc 3 , 90.Xr sqlite3_mutex_held 3 , 91.Xr sqlite3_mutex_alloc 3 , 92.Xr sqlite3_initialize 3 , 93.Xr SQLITE_CONFIG_SINGLETHREAD 3 94