diff options
Diffstat (limited to 'static/netbsd/man3/sqlite3_busy_handler.3')
| -rw-r--r-- | static/netbsd/man3/sqlite3_busy_handler.3 | 82 |
1 files changed, 82 insertions, 0 deletions
diff --git a/static/netbsd/man3/sqlite3_busy_handler.3 b/static/netbsd/man3/sqlite3_busy_handler.3 new file mode 100644 index 00000000..3ce2ae41 --- /dev/null +++ b/static/netbsd/man3/sqlite3_busy_handler.3 @@ -0,0 +1,82 @@ +.Dd January 24, 2024 +.Dt SQLITE3_BUSY_HANDLER 3 +.Os +.Sh NAME +.Nm sqlite3_busy_handler +.Nd register a callback to handle SQLITE_BUSY errors +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3_busy_handler +.Fa "sqlite3*" +.Fa "int(*)(void*,int)" +.Fa "void*" +.Fc +.Sh DESCRIPTION +The sqlite3_busy_handler(D,X,P) routine sets a callback function X +that might be invoked with argument P whenever an attempt is made to +access a database table associated with database connection +D when another thread or process has the table locked. +The sqlite3_busy_handler() interface is used to implement +.Fn sqlite3_busy_timeout +and PRAGMA busy_timeout. +.Pp +If the busy callback is NULL, then SQLITE_BUSY is returned +immediately upon encountering the lock. +If the busy callback is not NULL, then the callback might be invoked +with two arguments. +.Pp +The first argument to the busy handler is a copy of the void* pointer +which is the third argument to sqlite3_busy_handler(). +The second argument to the busy handler callback is the number of times +that the busy handler has been invoked previously for the same locking +event. +If the busy callback returns 0, then no additional attempts are made +to access the database and SQLITE_BUSY is returned to the +application. +If the callback returns non-zero, then another attempt is made to access +the database and the cycle repeats. +.Pp +The presence of a busy handler does not guarantee that it will be invoked +when there is lock contention. +If SQLite determines that invoking the busy handler could result in +a deadlock, it will go ahead and return SQLITE_BUSY to the +application instead of invoking the busy handler. +Consider a scenario where one process is holding a read lock that it +is trying to promote to a reserved lock and a second process is holding +a reserved lock that it is trying to promote to an exclusive lock. +The first process cannot proceed because it is blocked by the second +and the second process cannot proceed because it is blocked by the +first. +If both processes invoke the busy handlers, neither will make any progress. +Therefore, SQLite returns SQLITE_BUSY for the first process, +hoping that this will induce the first process to release its read +lock and allow the second process to proceed. +.Pp +The default busy callback is NULL. +.Pp +There can only be a single busy handler defined for each database connection. +Setting a new busy handler clears any previously set handler. +Note that calling +.Fn sqlite3_busy_timeout +or evaluating PRAGMA busy_timeout=N will change +the busy handler and thus clear any previously set busy handler. +.Pp +The busy callback should not take any actions which modify the database +connection that invoked the busy handler. +In other words, the busy handler is not reentrant. +Any such actions result in undefined behavior. +.Pp +A busy handler must not close the database connection or prepared statement +that invoked the busy handler. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 2781. +.Bd -literal +SQLITE_API int sqlite3_busy_handler(sqlite3*,int(*)(void*,int),void*); +.Ed +.Sh SEE ALSO +.Xr sqlite3 3 , +.Xr sqlite3_busy_timeout 3 , +.Xr sqlite3_stmt 3 , +.Xr SQLITE_OK 3 |