Corrections to the documentation for sqlite3_busy_handler(). Ticket #2160. (CVS 3585)

FossilOrigin-Name: 9614c0f99f27e8c6576a1a3ec5573b9bc414e8a8

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

manifest.uuid

@@ -1 +1 @@
-686beffa6956654fc43a2e3f1ea2896b86533774
+9614c0f99f27e8c6576a1a3ec5573b9bc414e8a8

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. 

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