1.Dd December 19, 2018 2.Dt SQLITE3_MUTEX_HELD 3 3.Os 4.Sh NAME 5.Nm sqlite3_mutex_held , 6.Nm sqlite3_mutex_notheld 7.Nd Mutex Verification Routines 8.Sh SYNOPSIS 9.Ft int 10.Fo sqlite3_mutex_held 11.Fa "sqlite3_mutex*" 12.Fc 13.Ft int 14.Fo sqlite3_mutex_notheld 15.Fa "sqlite3_mutex*" 16.Fc 17.Sh DESCRIPTION 18The sqlite3_mutex_held() and sqlite3_mutex_notheld() routines are intended 19for use inside assert() statements. 20The SQLite core never uses these routines except inside an assert() 21and applications are advised to follow the lead of the core. 22The SQLite core only provides implementations for these routines when 23it is compiled with the SQLITE_DEBUG flag. 24External mutex implementations are only required to provide these routines 25if SQLITE_DEBUG is defined and if NDEBUG is not defined. 26.Pp 27These routines should return true if the mutex in their argument is 28held or not held, respectively, by the calling thread. 29.Pp 30The implementation is not required to provide versions of these routines 31that actually work. 32If the implementation does not provide working versions of these routines, 33it should at least provide stubs that always return true so that one 34does not get spurious assertion failures. 35.Pp 36If the argument to sqlite3_mutex_held() is a NULL pointer then the 37routine should return 1. 38This seems counter-intuitive since clearly the mutex cannot be held 39if it does not exist. 40But the reason the mutex does not exist is because the build is not 41using mutexes. 42And we do not want the assert() containing the call to sqlite3_mutex_held() 43to fail, so a non-zero return is the appropriate thing to do. 44The sqlite3_mutex_notheld() interface should also return 1 when given 45a NULL pointer. 46