Enhance documentation of sqlite3_db_mutex(). (CVS 5861)

FossilOrigin-Name: 3aed410ab08557ec92101e5d7c4c90ba50555ddc

manifest

@@ -1,5 +1,5 @@
-C Avoid\sa\ssegfault\swhen\sOOM\son\sa\ssimple\sEXPLAIN\squery.\s\sTicket\s#3478.\s(CVS\s5860)
-D 2008-11-04T14:25:06
+C Enhance\sdocumentation\sof\ssqlite3_db_mutex().\s(CVS\s5861)
+D 2008-11-04T14:48:23
 F Makefile.arm-wince-mingw32ce-gcc fcd5e9cd67fe88836360bb4f9ef4cb7f8e2fb5a0
 F Makefile.in da817da72422f9b876602c225fcd17d6ca4182f7
 F Makefile.linux-gcc d53183f4aa6a9192d249731c90dbdffbd2c68654
@@ -150,7 +150,7 @@ F src/random.c a87afbd598aa877e23ac676ee92fd8ee5c786a51
 F src/resolve.c 266bb03d2b456fe68f5df2dd5687e7e88ff8088d
 F src/select.c 0d79c6c0b48b9d67a443853fd6add8c2967ba870
 F src/shell.c d83b578a8ccdd3e0e7fef4388a0887ce9f810967
-F src/sqlite.h.in 547b42c528ae337f7e5a0f547d013b8085d13b80
+F src/sqlite.h.in 2e1df3481504c85e3575e959685a8a748d1760c6
 F src/sqlite3ext.h 1db7d63ab5de4b3e6b83dd03d1a4e64fef6d2a17
 F src/sqliteInt.h 926279c94cdf21e53fc66badb8541d94aed25018
 F src/sqliteLimit.h f435e728c6b620ef7312814d660a81f9356eb5c8
@@ -654,7 +654,7 @@ F tool/speedtest16.c c8a9c793df96db7e4933f0852abb7a03d48f2e81
 F tool/speedtest2.tcl ee2149167303ba8e95af97873c575c3e0fab58ff
 F tool/speedtest8.c 2902c46588c40b55661e471d7a86e4dd71a18224
 F tool/speedtest8inst1.c 293327bc76823f473684d589a8160bde1f52c14e
-P d95de32e8ded397adeef8f7a29b87bc85669ac95
-R 311b672b2aa5220681c6b634ffa28a60
+P acf26cc0f77b3a308d86f6dc02ecda66a4b12fd0
+R 967144092ed873369fe78115fcdbc885
 U drh
-Z 3b3f6a00601535b79e178ee5461e8314
+Z 0eeff37a296b9ff7c87511616dad08b9

manifest.uuid

@@ -1 +1 @@
-acf26cc0f77b3a308d86f6dc02ecda66a4b12fd0
+3aed410ab08557ec92101e5d7c4c90ba50555ddc

src/sqlite.h.in

@@ -30,7 +30,7 @@
 ** the version number) and changes its name to "sqlite3.h" as
 ** part of the build process.
 **
-** @(#) $Id: sqlite.h.in,v 1.407 2008/11/04 13:46:28 drh Exp $
+** @(#) $Id: sqlite.h.in,v 1.408 2008/11/04 14:48:23 drh Exp $
 */
 #ifndef _SQLITE3_H_
 #define _SQLITE3_H_
@@ -2672,6 +2672,16 @@ int sqlite3_open_v2(
 ** However, the error string might be overwritten or deallocated by
 ** subsequent calls to other SQLite interface functions.
 **
+** When the serialized [threading mode] is in use, it might be the
+** case that a second error occurs on a separate thread in between
+** the time of the first error and the call to these interfaces.
+** When that happens, the second error will be reported since these
+** interfaces always report the most recent result.  To avoid
+** this, each thread can obtain exclusive use of the [database connection] D
+** by invoking [sqlite3_mutex_enter]([sqlite3_db_mutex](D)) before beginning
+** to use D and invoking [sqlite3_mutex_leave]([sqlite3_db_mutex](D)) after
+** all calls to the interfaces listed here are completed.
+**
 ** If an interface fails with SQLITE_MISUSE, that means the interface
 ** was invoked incorrectly by the application.  In that case, the
 ** error code and message may or may not be set.