From 13aebc66f23fda99a10e694a75874ec5a57181c8 Mon Sep 17 00:00:00 2001 From: drh Date: Thu, 16 Jun 2005 19:48:39 +0000 Subject: [PATCH] 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 | 14 +++++++------- manifest.uuid | 2 +- www/capi3ref.tcl | 12 +++++++++--- www/faq.tcl | 24 +++++++++++++++--------- 4 files changed, 32 insertions(+), 20 deletions(-) diff --git a/manifest b/manifest index f714e04349..1717efa617 100644 --- a/manifest +++ b/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) -D 2005-06-16T18:47:39 +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-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 -R 4ca41c6cea7e59473590468b9797e8d7 +P 98a4de76e0593ef1d1d3e8b785d420cd554a08e8 +R 066b49d2a4cff736f75321641f980036 U drh -Z 1e3fd8e4bb12da8eb2b82638f8e04384 +Z 6ffd2eee9b1958837812c18f5ad7610d diff --git a/manifest.uuid b/manifest.uuid index 65730790ab..613c1c0ec8 100644 --- a/manifest.uuid +++ b/manifest.uuid @@ -1 +1 @@ -98a4de76e0593ef1d1d3e8b785d420cd554a08e8 \ No newline at end of file +59c95731f70ed9b9e135584f62d0a2b0f1a3bb96 \ No newline at end of file diff --git a/www/capi3ref.tcl b/www/capi3ref.tcl index 8e1562239a..aa94c2b8ff 100644 --- a/www/capi3ref.tcl +++ b/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 - is being used simultaneously by two or more threads. + SQLITE_DONE. Or it could be the case that a database connection + is being used by a different thread than the one it was created it. } api {} { diff --git a/www/faq.tcl b/www/faq.tcl index 9ffebb1e61..1879ef48c1 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.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} @@ -52,7 +52,7 @@ INSERT INTO t1 VALUES((SELECT max(a) FROM t1)+1,123); earlier.

Beginning with version 2.2.3, there is a new API function named - sqlite_last_insert_rowid() which will return the integer key + sqlite3_last_insert_rowid() which will return the integer key for the most recent insert operation. See the API documentation for details.

@@ -217,8 +217,8 @@ faq {

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 sqlite_busy_handler() or - sqlite_busy_timeout() API functions. See the API documentation + adjust this behavior from C code using the sqlite3_busy_handler() or + sqlite3_busy_timeout() API functions. See the API documentation for details.

If two or more processes have the same database open and one @@ -238,11 +238,17 @@ faq { recompile.

"Threadsafe" in the previous paragraph means that two or more threads - can run SQLite at the same time on different "sqlite" structures - returned from separate calls to sqlite_open(). It is never safe - to use the same sqlite structure pointer simultaneously in two + can run SQLite at the same time on different "sqlite3" structures + returned from separate calls to sqlite3_open(). It is never safe + to use the same sqlite3 structure pointer simultaneously in two or more threads.

+

An sqlite3 structure can only be used in the same thread + that called sqlite3_open 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.

+

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 } { -

If you are running the sqlite command-line access program +

If you are running the sqlite3 command-line access program you can type ".tables" to get a list of all tables. Or you can type ".schema" to see the complete database schema including all tables and indices. Either of these commands can be followed by @@ -327,7 +333,7 @@ faq {

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 sqlite_create_function() API) + by the sqlite3_create_function() API) may not exceed 255 characters in length.

}