From: drh <drh@noemail.net>
Date: Wed, 27 Jun 2007 00:08:39 +0000 (+0000)
Subject: Update the FAQ to describe how moving sqlite3 handles across threads is
X-Git-Tag: version-3.6.10~2038
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=6d31df30d82f4f71c84d3eb43ebd50dd8e6f2271;p=thirdparty%2Fsqlite.git

Update the FAQ to describe how moving sqlite3 handles across threads is
not safe with SQLITE_ENABLE_MEMORY_MANAGEMENT.  Tickets #2357 and #2463. (CVS 4136)

FossilOrigin-Name: 2640f518deba1d196201fac903ec4d3ab26d4bb3
---

diff --git a/manifest b/manifest
index b801b0d62c..36fcc4e09f 100644
--- a/manifest
+++ b/manifest
@@ -1,5 +1,5 @@
-C Make\ssure\sthe\sTCL\sbindings\salways\suse\sTcl_GetWideIntFromObj()\seven\sif\sthe\nreported\stype\sis\s"int"\sbecause\son\sx86-64\sand\s"int"\stype\sis\s64-bits.\nTicket\s#2465.\s(CVS\s4135)
-D 2007-06-26T22:55:38
+C Update\sthe\sFAQ\sto\sdescribe\show\smoving\ssqlite3\shandles\sacross\sthreads\sis\nnot\ssafe\swith\sSQLITE_ENABLE_MEMORY_MANAGEMENT.\s\sTickets\s#2357\sand\s#2463.\s(CVS\s4136)
+D 2007-06-27T00:08:40
 F Makefile.in 7f7485a4cc039476a42e534b3f26ec90e2f9753e
 F Makefile.linux-gcc 65241babba6faf1152bf86574477baab19190499
 F README 9c4e2d6706bdcc3efdd773ce752a8cdab4f90028
@@ -485,7 +485,7 @@ F www/direct1b.gif 32b48b764244817b6b591898dc52a04299a7b8a7
 F www/docs.tcl 09eeac4e565789a67abc63f166a9ae7f3050454d
 F www/download.tcl d59a0244f22a975c3f9deafb535fc20549cb8c45
 F www/dynload.tcl 02eb8273aa78cfa9070dd4501dca937fb22b466c
-F www/faq.tcl 98179bd65a60b0405b716e554c50bc817a5e39be
+F www/faq.tcl bf83ec841224518fb570c31325f502d7a3e632e7
 F www/fileformat.tcl 900c95b9633abc3dcfc384d9ddd8eb4876793059
 F www/formatchng.tcl bbb8af1ee494a71031acac4c8d8c51535f23b9df
 F www/fullscanb.gif f7c94cb227f060511f8909e10f570157263e9a25
@@ -516,7 +516,7 @@ F www/tclsqlite.tcl 8be95ee6dba05eabcd27a9d91331c803f2ce2130
 F www/vdbe.tcl 87a31ace769f20d3627a64fa1fade7fed47b90d0
 F www/version3.tcl 890248cf7b70e60c383b0e84d77d5132b3ead42b
 F www/whentouse.tcl fc46eae081251c3c181bd79c5faef8195d7991a5
-P 3daf7cae18ae2ee6404f770e69e4cd0c715615e5
-R 6bd5371797b28b1ad783bfd355bc5a05
+P 5c93324b937b4d8394b0eb7d7fe74f7965623cbe
+R f301b87e0a5b037cd827261dc87d1b34
 U drh
-Z 0e3284889f389cc363d1804b624bb69e
+Z 516a346f8c7e5fef81f1bad761ac02ef
diff --git a/manifest.uuid b/manifest.uuid
index fc1b561213..1503ae2095 100644
--- a/manifest.uuid
+++ b/manifest.uuid
@@ -1 +1 @@
-5c93324b937b4d8394b0eb7d7fe74f7965623cbe
\ No newline at end of file
+2640f518deba1d196201fac903ec4d3ab26d4bb3
\ No newline at end of file
diff --git a/www/faq.tcl b/www/faq.tcl
index c68c6de4b5..af6e080b8b 100644
--- a/www/faq.tcl
+++ b/www/faq.tcl
@@ -1,7 +1,7 @@
 #
 # Run this script to generated a faq.html output file
 #
-set rcsid {$Id: faq.tcl,v 1.37 2007/06/09 09:53:51 drh Exp $}
+set rcsid {$Id: faq.tcl,v 1.38 2007/06/27 00:08:40 drh Exp $}
 source common.tcl
 header {SQLite Frequently Asked Questions</title>}
 
@@ -154,8 +154,8 @@ faq {
   <p>When SQLite tries to access a file that is locked by another
   process, the default behavior is to return SQLITE_BUSY.  You can
   adjust this behavior from C code using the 
-  <a href="capi3ref#sqlite3_busy_handler">sqlite3_busy_handler()</a> or
-  <a href="capi3ref#sqlite3_busy_timeout">sqlite3_busy_timeout()</a>
+  <a href="capi3ref.html#sqlite3_busy_handler">sqlite3_busy_handler()</a> or
+  <a href="capi3ref.html#sqlite3_busy_timeout">sqlite3_busy_timeout()</a>
   API functions.</p>
 }
 
@@ -171,13 +171,14 @@ faq {
   <p>"Threadsafe" in the previous paragraph means that two or more threads
   can run SQLite at the same time on different "<b>sqlite3</b>" structures
   returned from separate calls to 
-  <a href="capi3ref#sqlite3_open">sqlite3_open()</a>.  It is never safe
+  <a href="capi3ref.html#sqlite3_open">sqlite3_open()</a>.  It is never safe
   to use the same <b>sqlite3</b> structure pointer in two
   or more threads.</p>
 
   <p>Prior to version 3.3.1,
   an <b>sqlite3</b> structure could only be used in the same thread
-  that called <a href="capi3ref#sqlite3_open">sqlite3_open</a> to create it.
+  that called <a href="capi3ref.html#sqlite3_open">sqlite3_open</a>
+  to create it.
   You could not open a
   database in one thread then pass the handle off to another thread for
   it to use.  This was due to limitations (bugs?) in many common threading
@@ -194,6 +195,17 @@ faq {
   can safely assume that no locks are being held if no
   transaction is pending and all statements have been finalized.</p>
 
+  <p>If you turn on
+  <a href="capi3ref.html#sqlite3_enable_shared_cache">shared cache</a>
+  mode or if you compile with the -DSQLITE_ENABLE_MEMORY_MANAGEMENT=1
+  option, then you can never move an <b>sqlite3</b> pointer across
+  threads.  The <b>sqlite3</b> pointer must only be used in the same
+  thread in which it was created by 
+  <a href="capi3ref.html#sqlite3_open">sqlite3_open()</a>.  If you
+  break the rules and use an <b>sqlite3</b> in more than one thread
+  under these circumstances, then you will likely corrupt some
+  internal data structures resulting in a crash.</p>
+
   <p>Under UNIX, you should not carry an open SQLite database across
   a fork() system call into the child process.  Problems will result
   if you do.</p>