74 lines
2.9 KiB
Groff
74 lines
2.9 KiB
Groff
.Dd December 19, 2018
|
|
.Dt SQLITE3_BUSY_HANDLER 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm sqlite3_busy_handler
|
|
.Nd Register A Callback To Handle SQLITE_BUSY Errors
|
|
.Sh SYNOPSIS
|
|
.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 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 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 SEE ALSO
|
|
.Xr sqlite3 3 ,
|
|
.Xr sqlite3_stmt 3 ,
|
|
.Xr sqlite3_busy_timeout 3 ,
|
|
.Xr SQLITE_OK 3
|