1.Dd $Mdocdate$ 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. 65If it returns NULL that means that a mutex could not be allocated. 66SQLite will unwind its stack and return an error. 67The argument to sqlite3_mutex_alloc() is 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_MEM2 79.It 80SQLITE_MUTEX_STATIC_PRNG 81.It 82SQLITE_MUTEX_STATIC_LRU 83.It 84SQLITE_MUTEX_STATIC_LRU2 85.El 86.Pp 87The first two constants (SQLITE_MUTEX_FAST and SQLITE_MUTEX_RECURSIVE) 88cause sqlite3_mutex_alloc() to create a new mutex. 89The new mutex is recursive when SQLITE_MUTEX_RECURSIVE is used but 90not necessarily so when SQLITE_MUTEX_FAST is used. 91The mutex implementation does not need to make a distinction between 92SQLITE_MUTEX_RECURSIVE and SQLITE_MUTEX_FAST if it does not want to. 93SQLite will only request a recursive mutex in cases where it really 94needs one. 95If a faster non-recursive mutex implementation is available on the 96host platform, the mutex subsystem might return such a mutex in response 97to SQLITE_MUTEX_FAST. 98.Pp 99The other allowed parameters to sqlite3_mutex_alloc() (anything other 100than SQLITE_MUTEX_FAST and SQLITE_MUTEX_RECURSIVE) each return a pointer 101to a static preexisting mutex. 102Six static mutexes are used by the current version of SQLite. 103Future versions of SQLite may add additional static mutexes. 104Static mutexes are for internal use by SQLite only. 105Applications that use SQLite mutexes should use only the dynamic mutexes 106returned by SQLITE_MUTEX_FAST or SQLITE_MUTEX_RECURSIVE. 107.Pp 108Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST 109or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc() returns 110a different mutex on every call. 111But for the static mutex types, the same mutex is returned on every 112call that has the same type number. 113.Pp 114The sqlite3_mutex_free() routine deallocates a previously allocated 115dynamic mutex. 116SQLite is careful to deallocate every dynamic mutex that it allocates. 117The dynamic mutexes must not be in use when they are deallocated. 118Attempting to deallocate a static mutex results in undefined behavior. 119SQLite never deallocates a static mutex. 120.Pp 121The sqlite3_mutex_enter() and sqlite3_mutex_try() routines attempt 122to enter a mutex. 123If another thread is already within the mutex, sqlite3_mutex_enter() 124will block and sqlite3_mutex_try() will return SQLITE_BUSY. 125The sqlite3_mutex_try() interface returns SQLITE_OK upon successful 126entry. 127Mutexes created using SQLITE_MUTEX_RECURSIVE can be entered multiple 128times by the same thread. 129In such cases the, mutex must be exited an equal number of times before 130another thread can enter. 131If the same thread tries to enter any other kind of mutex more than 132once, the behavior is undefined. 133SQLite will never exhibit such behavior in its own use of mutexes. 134.Pp 135Some systems (for example, Windows 95) do not support the operation 136implemented by sqlite3_mutex_try(). 137On those systems, sqlite3_mutex_try() will always return SQLITE_BUSY. 138The SQLite core only ever uses sqlite3_mutex_try() as an optimization 139so this is acceptable behavior. 140.Pp 141The sqlite3_mutex_leave() routine exits a mutex that was previously 142entered by the same thread. 143The behavior is undefined if the mutex is not currently entered by 144the calling thread or is not currently allocated. 145SQLite will never do either. 146.Pp 147If the argument to sqlite3_mutex_enter(), sqlite3_mutex_try(), or sqlite3_mutex_leave() 148is a NULL pointer, then all three routines behave as no-ops. 149.Pp 150.Sh SEE ALSO 151.Xr sqlite3_mutex_held 3 , 152.Xr SQLITE_CONFIG_SINGLETHREAD 3 , 153.Xr SQLITE_OK 3 154