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