Change the documentation to explain that a database handle can only be

used in the same thread in which it was created.  Ticket #1272. (CVS 2521)

FossilOrigin-Name: 59c95731f70ed9b9e135584f62d0a2b0f1a3bb96

manifest

@@ -1,5 +1,5 @@
-C Fix\sthe\sTHREADSAFE\smacro\sin\sMakefile.in.\s\sWe\sreally\sneed\sto\srework\sthe\nwhole\sautoconf\sbuild\ssystem....\s(CVS\s2520)
+C Change\sthe\sdocumentation\sto\sexplain\sthat\sa\sdatabase\shandle\scan\sonly\sbe\nused\sin\sthe\ssame\sthread\sin\swhich\sit\swas\screated.\s\sTicket\s#1272.\s(CVS\s2521)
-D 2005-06-16T18:47:39
+D 2005-06-16T19:48:39
 F Makefile.in 64a6635ef44a98325e0cffe8d67669920a3dad47
 F Makefile.linux-gcc 06be33b2a9ad4f005a5f42b22c4a19dab3cbb5c7
 F README 9c4e2d6706bdcc3efdd773ce752a8cdab4f90028
@@ -246,7 +246,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 930afb4a565c092ed10e481c3c87a952f6989d83
+F www/capi3ref.tcl bf2ca74997fff2f460bc721c04165861e241a71a
 F www/changes.tcl 0bc369b91eb740ad0caa59ea9e0b8a640de56a4e
 F www/common.tcl de758130d54d95d151ea0d17a2ae5b92e1bb01de
 F www/compile.tcl 276546d7eb445add5a867193bbd80f6919a6b084
@@ -260,7 +260,7 @@ F www/different.tcl d01064946c588db0a0e87563a30aef1b3efb4434
 F www/docs.tcl 6c0b2c567404b15bd46a0cda2dc69615a8e679a8
 F www/download.tcl 3af00c0e8fd915961707cddb4c2260f5cf59f3c1
 F www/dynload.tcl 02eb8273aa78cfa9070dd4501dca937fb22b466c
-F www/faq.tcl 1e348dec52dc0f21f4216fd6918c69c56daa4cfd
+F www/faq.tcl 49f31a703f74c71ce66da646aaf18b07a5042672
 F www/fileformat.tcl 900c95b9633abc3dcfc384d9ddd8eb4876793059
 F www/formatchng.tcl 053ddb73646701353a5b1c9ca6274d5900739b45
 F www/index.tcl 9527f4eed69739cf5f81b3d75e0478d1c84d0a8a
@@ -281,7 +281,7 @@ F www/tclsqlite.tcl 425be741b8ae664f55cb1ef2371aab0a75109cf9
 F www/vdbe.tcl 87a31ace769f20d3627a64fa1fade7fed47b90d0
 F www/version3.tcl a99cf5f6d8bd4d5537584a2b342f0fb9fa601d8b
 F www/whentouse.tcl 528299b8316726dbcc5548e9aa0648c8b1bd055b
-P bc25397735c1485e3533507bed507250ea07534a
+P 98a4de76e0593ef1d1d3e8b785d420cd554a08e8
-R 4ca41c6cea7e59473590468b9797e8d7
+R 066b49d2a4cff736f75321641f980036
 U drh
-Z 1e3fd8e4bb12da8eb2b82638f8e04384
+Z 6ffd2eee9b1958837812c18f5ad7610d

manifest.uuid

@@ -1 +1 @@
-98a4de76e0593ef1d1d3e8b785d420cd554a08e8
+59c95731f70ed9b9e135584f62d0a2b0f1a3bb96

www/capi3ref.tcl

@@ -1,4 +1,4 @@
-set rcsid {$Id: capi3ref.tcl,v 1.22 2005/06/12 22:12:39 drh Exp $}
+set rcsid {$Id: capi3ref.tcl,v 1.23 2005/06/16 19:48:39 drh Exp $}
 source common.tcl
 header {C/C++ Interface For SQLite Version 3}
 puts {
@@ -846,6 +846,12 @@ int sqlite3_open16(
  Whether or not an error occurs when it is opened, resources associated
  with the sqlite3* handle should be released by passing it to
  sqlite3_close() when it is no longer required.
+
+ The returned sqlite3* can only be used in the same thread in which it
+ was created.  It is an error to call sqlite3_open() in one thread then
+ pass the resulting database handle off to another thread to use.  This
+ restriction is due to goofy design decisions (bugs?) in the way some
+ threading implementations interact with file locks.
 }
 
 api {} {
@@ -1048,8 +1054,8 @@ int sqlite3_step(sqlite3_stmt*);
  SQLITE_MISUSE means that the this routine was called inappropriately.
  Perhaps it was called on a virtual machine that had already been
  finalized or on one that had previously returned SQLITE_ERROR or
- SQLITE_DONE.  Or it could be the case the the same database connection
+ SQLITE_DONE.  Or it could be the case that a database connection
- is being used simultaneously by two or more threads.
+ is being used by a different thread than the one it was created it.
 }
 
 api {} {

www/faq.tcl

@@ -1,7 +1,7 @@
 #
 # Run this script to generated a faq.html output file
 #
-set rcsid {$Id: faq.tcl,v 1.28 2005/01/26 10:39:58 danielk1977 Exp $}
+set rcsid {$Id: faq.tcl,v 1.29 2005/06/16 19:48:40 drh Exp $}
 source common.tcl
 header {SQLite Frequently Asked Questions</title>}
 
@@ -52,7 +52,7 @@ INSERT INTO t1 VALUES((SELECT max(a) FROM t1)+1,123);
   earlier.</p>
 
   <p>Beginning with version 2.2.3, there is a new API function named
-  <b>sqlite_last_insert_rowid()</b> which will return the integer key
+  <b>sqlite3_last_insert_rowid()</b> which will return the integer key
   for the most recent insert operation.  See the API documentation for
   details.</p>
 
@@ -217,8 +217,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 <b>sqlite_busy_handler()</b> or
+  adjust this behavior from C code using the <b>sqlite3_busy_handler()</b> or
-  <b>sqlite_busy_timeout()</b> API functions.  See the API documentation
+  <b>sqlite3_busy_timeout()</b> API functions.  See the API documentation
   for details.</p>
 
   <p>If two or more processes have the same database open and one
@@ -238,11 +238,17 @@ faq {
   recompile.</p>
 
   <p>"Threadsafe" in the previous paragraph means that two or more threads
-  can run SQLite at the same time on different "<b>sqlite</b>" structures
+  can run SQLite at the same time on different "<b>sqlite3</b>" structures
-  returned from separate calls to <b>sqlite_open()</b>.  It is never safe
+  returned from separate calls to <b>sqlite3_open()</b>.  It is never safe
-  to use the same <b>sqlite</b> structure pointer simultaneously in two
+  to use the same <b>sqlite3</b> structure pointer simultaneously in two
   or more threads.</p>
 
+  <p>An <b>sqlite3</b> structure can only be used in the same thread
+  that called <b>sqlite3_open</b> to create it.  You cannot open a
+  database in one thread then pass the handle off to another thread for
+  it to use.  This is due to limitations (bugs?) in many common threading
+  implementations such as on RedHat9.</p>
+
   <p>Note that if two or more threads have the same database open and one
   thread creates a new table or index, the other threads might
   not be able to see the new table right away.  You might have to
@@ -257,7 +263,7 @@ faq {
 faq {
   How do I list all tables/indices contained in an SQLite database
 } {
-  <p>If you are running the <b>sqlite</b> command-line access program
+  <p>If you are running the <b>sqlite3</b> command-line access program
   you can type "<b>.tables</b>" to get a list of all tables.  Or you
   can type "<b>.schema</b>" to see the complete database schema including
   all tables and indices.  Either of these commands can be followed by
@@ -327,7 +333,7 @@ faq {
 
   <p>The names of tables, indices, view, triggers, and columns can be
   as long as desired.  However, the names of SQL functions (as created
-  by the <a href="c_interface.html#cfunc">sqlite_create_function()</a> API)
+  by the <a href="c_interface.html#cfunc">sqlite3_create_function()</a> API)
   may not exceed 255 characters in length.</p>
 }