1.Dd January 24, 2024 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.In sqlite3.h 10.Ft int 11.Fo sqlite3_mutex_held 12.Fa "sqlite3_mutex*" 13.Fc 14.Ft int 15.Fo sqlite3_mutex_notheld 16.Fa "sqlite3_mutex*" 17.Fc 18.Sh DESCRIPTION 19The sqlite3_mutex_held() and sqlite3_mutex_notheld() routines are intended 20for use inside assert() statements. 21The SQLite core never uses these routines except inside an assert() 22and applications are advised to follow the lead of the core. 23The SQLite core only provides implementations for these routines when 24it is compiled with the SQLITE_DEBUG flag. 25External mutex implementations are only required to provide these routines 26if SQLITE_DEBUG is defined and if NDEBUG is not defined. 27.Pp 28These routines should return true if the mutex in their argument is 29held or not held, respectively, by the calling thread. 30.Pp 31The implementation is not required to provide versions of these routines 32that actually work. 33If the implementation does not provide working versions of these routines, 34it should at least provide stubs that always return true so that one 35does not get spurious assertion failures. 36.Pp 37If the argument to sqlite3_mutex_held() is a NULL pointer then the 38routine should return 1. 39This seems counter-intuitive since clearly the mutex cannot be held 40if it does not exist. 41But the reason the mutex does not exist is because the build is not 42using mutexes. 43And we do not want the assert() containing the call to sqlite3_mutex_held() 44to fail, so a non-zero return is the appropriate thing to do. 45The sqlite3_mutex_notheld() interface should also return 1 when given 46a NULL pointer. 47.Sh IMPLEMENTATION NOTES 48These declarations were extracted from the 49interface documentation at line 8144. 50.Bd -literal 51#ifndef NDEBUG 52SQLITE_API int sqlite3_mutex_held(sqlite3_mutex*); 53SQLITE_API int sqlite3_mutex_notheld(sqlite3_mutex*); 54#endif 55.Ed 56