From 86939b598fe514ce83dcd9e32f4da6ffbafe39a3 Mon Sep 17 00:00:00 2001 From: drh Date: Wed, 10 Jan 2007 12:54:51 +0000 Subject: [PATCH] Corrections to the documentation for sqlite3_busy_handler(). Ticket #2160. (CVS 3585) FossilOrigin-Name: 9614c0f99f27e8c6576a1a3ec5573b9bc414e8a8 --- manifest | 14 +++++++------- manifest.uuid | 2 +- src/sqlite.h.in | 25 +++++++++++++++++++++---- www/capi3ref.tcl | 8 +++++--- 4 files changed, 34 insertions(+), 15 deletions(-) diff --git a/manifest b/manifest index fab18b898e..c3bd57f526 100644 --- a/manifest +++ b/manifest @@ -1,5 +1,5 @@ -C Documentation\supdates\sprior\sto\sversion\s3.3.10.\s\sAmong\sthe\schanges\sis\sa\nfix\sfor\sticket\s#2148\s(CVS\s3584) -D 2007-01-09T23:13:06 +C Corrections\sto\sthe\sdocumentation\sfor\ssqlite3_busy_handler().\s\sTicket\s#2160.\s(CVS\s3585) +D 2007-01-10T12:54:51 F Makefile.in 7fa74bf4359aa899da5586e394d17735f221315f F Makefile.linux-gcc 2d8574d1ba75f129aba2019f0b959db380a90935 F README 9c4e2d6706bdcc3efdd773ce752a8cdab4f90028 @@ -95,7 +95,7 @@ F src/random.c 6119474a6f6917f708c1dee25b9a8e519a620e88 F src/select.c 52f09127b53697b1a95835a9b0db9309cca8079f F src/server.c 087b92a39d883e3fa113cae259d64e4c7438bc96 F src/shell.c d13ca007cd18192c07a668aeddcdd6a9fe639be9 -F src/sqlite.h.in 2931f7ee2415e7a49fd12f386c23575046f0f540 +F src/sqlite.h.in e30302785dbc3bc267332c66aff3fc35094df82e F src/sqlite3ext.h 011c75fd6459a61454514af07c7a4f1f5c767f27 F src/sqliteInt.h 90dad3c0ba7a5151c48361748ccdada9ff2eff78 F src/table.c 6d0da66dde26ee75614ed8f584a1996467088d06 @@ -380,7 +380,7 @@ F www/audit.tcl 90e09d580f79c7efec0c7d6f447b7ec5c2dce5c0 F www/autoinc.tcl b357f5ba954b046ee35392ce0f884a2fcfcdea06 F www/c_interface.tcl b51b08591554c16a0c3ef718364a508ac25abc7e F www/capi3.tcl 7a7cc225fe02eb7ab861a6019b08baa0014409e1 -F www/capi3ref.tcl 105cad9948f77e0764af3bfcc97ac45f2cb63a2f +F www/capi3ref.tcl 05302a68539d59735db218b7a85286ed54ecb882 F www/changes.tcl dd6aaf7839ac20b3c5fe69533755bc64d8e43952 F www/common.tcl 14d121c28532ad20c3e349caa4db708b0b822083 F www/compile.tcl 276546d7eb445add5a867193bbd80f6919a6b084 @@ -424,7 +424,7 @@ F www/tclsqlite.tcl bb0d1357328a42b1993d78573e587c6dcbc964b9 F www/vdbe.tcl 87a31ace769f20d3627a64fa1fade7fed47b90d0 F www/version3.tcl 890248cf7b70e60c383b0e84d77d5132b3ead42b F www/whentouse.tcl 97e2b5cd296f7d8057e11f44427dea8a4c2db513 -P 4b36de46c42e2e42d611b38ff18949bea55c803b -R a900feeae70e7f64188ed8aec5186a0b +P 686beffa6956654fc43a2e3f1ea2896b86533774 +R 37b95f7cb770c1cc82421906a2f6ab32 U drh -Z 34a3ee0ac8765f98a93923ba5477552e +Z e0e0191c8f079c40c55e12d7cf52eaf1 diff --git a/manifest.uuid b/manifest.uuid index c410391b2b..944a647181 100644 --- a/manifest.uuid +++ b/manifest.uuid @@ -1 +1 @@ -686beffa6956654fc43a2e3f1ea2896b86533774 \ No newline at end of file +9614c0f99f27e8c6576a1a3ec5573b9bc414e8a8 \ No newline at end of file diff --git a/src/sqlite.h.in b/src/sqlite.h.in index 80450e88cb..7b08850a70 100644 --- a/src/sqlite.h.in +++ b/src/sqlite.h.in @@ -12,7 +12,7 @@ ** This header file defines the interface that the SQLite library ** presents to client programs. ** -** @(#) $Id: sqlite.h.in,v 1.195 2006/11/09 00:24:54 drh Exp $ +** @(#) $Id: sqlite.h.in,v 1.196 2007/01/10 12:54:51 drh Exp $ */ #ifndef _SQLITE3_H_ #define _SQLITE3_H_ @@ -315,13 +315,30 @@ int sqlite3_complete16(const void *sql); ** currently locked by another process or thread. If the busy callback ** is NULL, then sqlite3_exec() returns SQLITE_BUSY immediately if ** it finds a locked table. If the busy callback is not NULL, then -** sqlite3_exec() invokes the callback with three arguments. The -** second argument is the name of the locked table and the third -** argument is the number of times the table has been busy. If the +** sqlite3_exec() invokes the callback with two arguments. The +** first argument to the handler is a copy of the void* pointer which +** is the third argument to this routine. The second argument to +** the handler is the number of times that the busy handler has +** been invoked for this locking event. If the ** busy callback returns 0, then sqlite3_exec() immediately returns ** SQLITE_BUSY. If the callback returns non-zero, then sqlite3_exec() ** tries to open the table again and the cycle repeats. ** +** 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 return SQLITE_BUSY instead. +** 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. +** ** The default busy callback is NULL. ** ** Sqlite is re-entrant, so the busy handler may start a new query. diff --git a/www/capi3ref.tcl b/www/capi3ref.tcl index 600892d828..64fea9c196 100644 --- a/www/capi3ref.tcl +++ b/www/capi3ref.tcl @@ -1,4 +1,4 @@ -set rcsid {$Id: capi3ref.tcl,v 1.49 2007/01/09 15:06:42 drh Exp $} +set rcsid {$Id: capi3ref.tcl,v 1.50 2007/01/10 12:54:52 drh Exp $} source common.tcl header {C/C++ Interface For SQLite Version 3} puts { @@ -247,8 +247,10 @@ api {} { upon encountering the lock. If the busy callback is not NULL, then the callback will be invoked with two arguments. The - second argument is the number of prior calls to the busy callback - for the same lock. If the + first argument to the handler is a copy of the void* pointer which + is the third argument to this routine. The second argument to + the handler is the number of times that the busy handler has + been invoked for this locking event. If the busy callback returns 0, then no additional attempts are made to access the database and SQLITE_BUSY is returned. If the callback returns non-zero, then another attempt is made to open the -- 2.47.2