Enhance documentation of sqlite3_db_mutex(). (CVS 5861)

FossilOrigin-Name: 3aed410ab08557ec92101e5d7c4c90ba50555ddc

1 files changed, 11 insertions, 1 deletions

diff --git a/src/sqlite.h.in b/src/sqlite.h.in
index 3ee2d13b4..34880884e 100644
--- a/src/sqlite.h.in
+++ b/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.