diff options
Diffstat (limited to 'static/netbsd/man3/sqlite3_mutex_alloc.3')
| -rw-r--r-- | static/netbsd/man3/sqlite3_mutex_alloc.3 | 175 |
1 files changed, 175 insertions, 0 deletions
diff --git a/static/netbsd/man3/sqlite3_mutex_alloc.3 b/static/netbsd/man3/sqlite3_mutex_alloc.3 new file mode 100644 index 00000000..3d000fd6 --- /dev/null +++ b/static/netbsd/man3/sqlite3_mutex_alloc.3 @@ -0,0 +1,175 @@ +.Dd January 24, 2024 +.Dt SQLITE3_MUTEX_ALLOC 3 +.Os +.Sh NAME +.Nm sqlite3_mutex_alloc , +.Nm sqlite3_mutex_free , +.Nm sqlite3_mutex_enter , +.Nm sqlite3_mutex_try , +.Nm sqlite3_mutex_leave +.Nd mutexes +.Sh SYNOPSIS +.In sqlite3.h +.Ft sqlite3_mutex * +.Fo sqlite3_mutex_alloc +.Fa "int" +.Fc +.Ft void +.Fo sqlite3_mutex_free +.Fa "sqlite3_mutex*" +.Fc +.Ft void +.Fo sqlite3_mutex_enter +.Fa "sqlite3_mutex*" +.Fc +.Ft int +.Fo sqlite3_mutex_try +.Fa "sqlite3_mutex*" +.Fc +.Ft void +.Fo sqlite3_mutex_leave +.Fa "sqlite3_mutex*" +.Fc +.Sh DESCRIPTION +The SQLite core uses these routines for thread synchronization. +Though they are intended for internal use by SQLite, code that links +against SQLite is permitted to use any of these routines. +.Pp +The SQLite source code contains multiple implementations of these mutex +routines. +An appropriate implementation is selected automatically at compile-time. +The following implementations are available in the SQLite core: +.Bl -bullet +.It +SQLITE_MUTEX_PTHREADS +.It +SQLITE_MUTEX_W32 +.It +SQLITE_MUTEX_NOOP +.El +.Pp +The SQLITE_MUTEX_NOOP implementation is a set of routines that does +no real locking and is appropriate for use in a single-threaded application. +The SQLITE_MUTEX_PTHREADS and SQLITE_MUTEX_W32 implementations are +appropriate for use on Unix and Windows. +.Pp +If SQLite is compiled with the SQLITE_MUTEX_APPDEF preprocessor macro +defined (with "-DSQLITE_MUTEX_APPDEF=1"), then no mutex implementation +is included with the library. +In this case the application must supply a custom mutex implementation +using the SQLITE_CONFIG_MUTEX option of the sqlite3_config() +function before calling sqlite3_initialize() or any other public sqlite3_ +function that calls sqlite3_initialize(). +.Pp +The sqlite3_mutex_alloc() routine allocates a new mutex and returns +a pointer to it. +The sqlite3_mutex_alloc() routine returns NULL if it is unable to allocate +the requested mutex. +The argument to sqlite3_mutex_alloc() must one of these integer constants: +.Bl -bullet +.It +SQLITE_MUTEX_FAST +.It +SQLITE_MUTEX_RECURSIVE +.It +SQLITE_MUTEX_STATIC_MAIN +.It +SQLITE_MUTEX_STATIC_MEM +.It +SQLITE_MUTEX_STATIC_OPEN +.It +SQLITE_MUTEX_STATIC_PRNG +.It +SQLITE_MUTEX_STATIC_LRU +.It +SQLITE_MUTEX_STATIC_PMEM +.It +SQLITE_MUTEX_STATIC_APP1 +.It +SQLITE_MUTEX_STATIC_APP2 +.It +SQLITE_MUTEX_STATIC_APP3 +.It +SQLITE_MUTEX_STATIC_VFS1 +.It +SQLITE_MUTEX_STATIC_VFS2 +.It +SQLITE_MUTEX_STATIC_VFS3 +.El +.Pp +The first two constants (SQLITE_MUTEX_FAST and SQLITE_MUTEX_RECURSIVE) +cause sqlite3_mutex_alloc() to create a new mutex. +The new mutex is recursive when SQLITE_MUTEX_RECURSIVE is used but +not necessarily so when SQLITE_MUTEX_FAST is used. +The mutex implementation does not need to make a distinction between +SQLITE_MUTEX_RECURSIVE and SQLITE_MUTEX_FAST if it does not want to. +SQLite will only request a recursive mutex in cases where it really +needs one. +If a faster non-recursive mutex implementation is available on the +host platform, the mutex subsystem might return such a mutex in response +to SQLITE_MUTEX_FAST. +.Pp +The other allowed parameters to sqlite3_mutex_alloc() (anything other +than SQLITE_MUTEX_FAST and SQLITE_MUTEX_RECURSIVE) each return a pointer +to a static preexisting mutex. +Nine static mutexes are used by the current version of SQLite. +Future versions of SQLite may add additional static mutexes. +Static mutexes are for internal use by SQLite only. +Applications that use SQLite mutexes should use only the dynamic mutexes +returned by SQLITE_MUTEX_FAST or SQLITE_MUTEX_RECURSIVE. +.Pp +Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST +or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc() returns +a different mutex on every call. +For the static mutex types, the same mutex is returned on every call +that has the same type number. +.Pp +The sqlite3_mutex_free() routine deallocates a previously allocated +dynamic mutex. +Attempting to deallocate a static mutex results in undefined behavior. +.Pp +The sqlite3_mutex_enter() and sqlite3_mutex_try() routines attempt +to enter a mutex. +If another thread is already within the mutex, sqlite3_mutex_enter() +will block and sqlite3_mutex_try() will return SQLITE_BUSY. +The sqlite3_mutex_try() interface returns SQLITE_OK upon successful +entry. +Mutexes created using SQLITE_MUTEX_RECURSIVE can be entered multiple +times by the same thread. +In such cases, the mutex must be exited an equal number of times before +another thread can enter. +If the same thread tries to enter any mutex other than an SQLITE_MUTEX_RECURSIVE +more than once, the behavior is undefined. +.Pp +Some systems (for example, Windows 95) do not support the operation +implemented by sqlite3_mutex_try(). +On those systems, sqlite3_mutex_try() will always return SQLITE_BUSY. +In most cases the SQLite core only uses sqlite3_mutex_try() as an optimization, +so this is acceptable behavior. +The exceptions are unix builds that set the SQLITE_ENABLE_SETLK_TIMEOUT +build option. +In that case a working sqlite3_mutex_try() is required. +.Pp +The sqlite3_mutex_leave() routine exits a mutex that was previously +entered by the same thread. +The behavior is undefined if the mutex is not currently entered by +the calling thread or is not currently allocated. +.Pp +If the argument to sqlite3_mutex_enter(), sqlite3_mutex_try(), sqlite3_mutex_leave(), +or sqlite3_mutex_free() is a NULL pointer, then any of the four routines +behaves as a no-op. +.Pp +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 7944. +.Bd -literal +SQLITE_API sqlite3_mutex *sqlite3_mutex_alloc(int); +SQLITE_API void sqlite3_mutex_free(sqlite3_mutex*); +SQLITE_API void sqlite3_mutex_enter(sqlite3_mutex*); +SQLITE_API int sqlite3_mutex_try(sqlite3_mutex*); +SQLITE_API void sqlite3_mutex_leave(sqlite3_mutex*); +.Ed +.Sh SEE ALSO +.Xr sqlite3_mutex_held 3 , +.Xr SQLITE_CONFIG_SINGLETHREAD 3 , +.Xr SQLITE_OK 3 |