.Dd January 24, 2024
.Dt SQLITE3_MUTEX_HELD 3
.Os
.Sh NAME
.Nm sqlite3_mutex_held ,
.Nm sqlite3_mutex_notheld
.Nd mutex verification routines
.Sh SYNOPSIS
.In sqlite3.h
.Ft int
.Fo sqlite3_mutex_held
.Fa "sqlite3_mutex*"
.Fc
.Ft int
.Fo sqlite3_mutex_notheld
.Fa "sqlite3_mutex*"
.Fc
.Sh DESCRIPTION
The sqlite3_mutex_held() and sqlite3_mutex_notheld() routines are intended
for use inside assert() statements.
The SQLite core never uses these routines except inside an assert()
and applications are advised to follow the lead of the core.
The SQLite core only provides implementations for these routines when
it is compiled with the SQLITE_DEBUG flag.
External mutex implementations are only required to provide these routines
if SQLITE_DEBUG is defined and if NDEBUG is not defined.
.Pp
These routines should return true if the mutex in their argument is
held or not held, respectively, by the calling thread.
.Pp
The implementation is not required to provide versions of these routines
that actually work.
If the implementation does not provide working versions of these routines,
it should at least provide stubs that always return true so that one
does not get spurious assertion failures.
.Pp
If the argument to sqlite3_mutex_held() is a NULL pointer then the
routine should return 1.
This seems counter-intuitive since clearly the mutex cannot be held
if it does not exist.
But the reason the mutex does not exist is because the build is not
using mutexes.
And we do not want the assert() containing the call to sqlite3_mutex_held()
to fail, so a non-zero return is the appropriate thing to do.
The sqlite3_mutex_notheld() interface should also return 1 when given
a NULL pointer.
.Sh IMPLEMENTATION NOTES
These declarations were extracted from the
interface documentation at line 8144.
.Bd -literal
#ifndef NDEBUG
SQLITE_API int sqlite3_mutex_held(sqlite3_mutex*);
SQLITE_API int sqlite3_mutex_notheld(sqlite3_mutex*);
#endif
.Ed