1.Dd December 19, 2018 2.Dt SQLITE3_MUTEX_ALLOC 3 3.Os 4.Sh NAME 5.Nm sqlite3_mutex_alloc , 6.Nm sqlite3_mutex_free , 7.Nm sqlite3_mutex_enter , 8.Nm sqlite3_mutex_try , 9.Nm sqlite3_mutex_leave 10.Nd Mutexes 11.Sh SYNOPSIS 12.Ft sqlite3_mutex * 13.Fo sqlite3_mutex_alloc 14.Fa "int" 15.Fc 16.Ft void 17.Fo sqlite3_mutex_free 18.Fa "sqlite3_mutex*" 19.Fc 20.Ft void 21.Fo sqlite3_mutex_enter 22.Fa "sqlite3_mutex*" 23.Fc 24.Ft int 25.Fo sqlite3_mutex_try 26.Fa "sqlite3_mutex*" 27.Fc 28.Ft void 29.Fo sqlite3_mutex_leave 30.Fa "sqlite3_mutex*" 31.Fc 32.Sh DESCRIPTION 33The SQLite core uses these routines for thread synchronization. 34Though they are intended for internal use by SQLite, code that links 35against SQLite is permitted to use any of these routines. 36.Pp 37The SQLite source code contains multiple implementations of these mutex 38routines. 39An appropriate implementation is selected automatically at compile-time. 40The following implementations are available in the SQLite core: 41.Bl -bullet 42.It 43SQLITE_MUTEX_PTHREADS 44.It 45SQLITE_MUTEX_W32 46.It 47SQLITE_MUTEX_NOOP 48.El 49.Pp 50The SQLITE_MUTEX_NOOP implementation is a set of routines that does 51no real locking and is appropriate for use in a single-threaded application. 52The SQLITE_MUTEX_PTHREADS and SQLITE_MUTEX_W32 implementations are 53appropriate for use on Unix and Windows. 54.Pp 55If SQLite is compiled with the SQLITE_MUTEX_APPDEF preprocessor macro 56defined (with "-DSQLITE_MUTEX_APPDEF=1"), then no mutex implementation 57is included with the library. 58In this case the application must supply a custom mutex implementation 59using the SQLITE_CONFIG_MUTEX option of the sqlite3_config() 60function before calling sqlite3_initialize() or any other public sqlite3_ 61function that calls sqlite3_initialize(). 62.Pp 63The sqlite3_mutex_alloc() routine allocates a new mutex and returns 64a pointer to it. 65The sqlite3_mutex_alloc() routine returns NULL if it is unable to allocate 66the requested mutex. 67The argument to sqlite3_mutex_alloc() must one of these integer constants: 68.Bl -bullet 69.It 70SQLITE_MUTEX_FAST 71.It 72SQLITE_MUTEX_RECURSIVE 73.It 74SQLITE_MUTEX_STATIC_MASTER 75.It 76SQLITE_MUTEX_STATIC_MEM 77.It 78SQLITE_MUTEX_STATIC_OPEN 79.It 80SQLITE_MUTEX_STATIC_PRNG 81.It 82SQLITE_MUTEX_STATIC_LRU 83.It 84SQLITE_MUTEX_STATIC_PMEM 85.It 86SQLITE_MUTEX_STATIC_APP1 87.It 88SQLITE_MUTEX_STATIC_APP2 89.It 90SQLITE_MUTEX_STATIC_APP3 91.It 92SQLITE_MUTEX_STATIC_VFS1 93.It 94SQLITE_MUTEX_STATIC_VFS2 95.It 96SQLITE_MUTEX_STATIC_VFS3 97.El 98.Pp 99The first two constants (SQLITE_MUTEX_FAST and SQLITE_MUTEX_RECURSIVE) 100cause sqlite3_mutex_alloc() to create a new mutex. 101The new mutex is recursive when SQLITE_MUTEX_RECURSIVE is used but 102not necessarily so when SQLITE_MUTEX_FAST is used. 103The mutex implementation does not need to make a distinction between 104SQLITE_MUTEX_RECURSIVE and SQLITE_MUTEX_FAST if it does not want to. 105SQLite will only request a recursive mutex in cases where it really 106needs one. 107If a faster non-recursive mutex implementation is available on the 108host platform, the mutex subsystem might return such a mutex in response 109to SQLITE_MUTEX_FAST. 110.Pp 111The other allowed parameters to sqlite3_mutex_alloc() (anything other 112than SQLITE_MUTEX_FAST and SQLITE_MUTEX_RECURSIVE) each return a pointer 113to a static preexisting mutex. 114Nine static mutexes are used by the current version of SQLite. 115Future versions of SQLite may add additional static mutexes. 116Static mutexes are for internal use by SQLite only. 117Applications that use SQLite mutexes should use only the dynamic mutexes 118returned by SQLITE_MUTEX_FAST or SQLITE_MUTEX_RECURSIVE. 119.Pp 120Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST 121or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc() returns 122a different mutex on every call. 123For the static mutex types, the same mutex is returned on every call 124that has the same type number. 125.Pp 126The sqlite3_mutex_free() routine deallocates a previously allocated 127dynamic mutex. 128Attempting to deallocate a static mutex results in undefined behavior. 129.Pp 130The sqlite3_mutex_enter() and sqlite3_mutex_try() routines attempt 131to enter a mutex. 132If another thread is already within the mutex, sqlite3_mutex_enter() 133will block and sqlite3_mutex_try() will return SQLITE_BUSY. 134The sqlite3_mutex_try() interface returns SQLITE_OK upon successful 135entry. 136Mutexes created using SQLITE_MUTEX_RECURSIVE can be entered multiple 137times by the same thread. 138In such cases, the mutex must be exited an equal number of times before 139another thread can enter. 140If the same thread tries to enter any mutex other than an SQLITE_MUTEX_RECURSIVE 141more than once, the behavior is undefined. 142.Pp 143Some systems (for example, Windows 95) do not support the operation 144implemented by sqlite3_mutex_try(). 145On those systems, sqlite3_mutex_try() will always return SQLITE_BUSY. 146The SQLite core only ever uses sqlite3_mutex_try() as an optimization 147so this is acceptable behavior. 148.Pp 149The sqlite3_mutex_leave() routine exits a mutex that was previously 150entered by the same thread. 151The behavior is undefined if the mutex is not currently entered by 152the calling thread or is not currently allocated. 153.Pp 154If the argument to sqlite3_mutex_enter(), sqlite3_mutex_try(), or sqlite3_mutex_leave() 155is a NULL pointer, then all three routines behave as no-ops. 156.Pp 157.Sh SEE ALSO 158.Xr sqlite3_mutex_held 3 , 159.Xr SQLITE_CONFIG_SINGLETHREAD 3 , 160.Xr SQLITE_OK 3 161