46 lines
1.6 KiB
Groff
46 lines
1.6 KiB
Groff
.Dd March 11, 2017
|
|
.Dt SQLITE3_MUTEX_HELD 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm sqlite3_mutex_held ,
|
|
.Nm sqlite3_mutex_notheld
|
|
.Nd Mutex Verification Routines
|
|
.Sh SYNOPSIS
|
|
.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.
|