Shuffle some of the mutex related documentation in sqlite.h.in to match the new sqlite3_mutex_methods based API. (CVS 5244)

FossilOrigin-Name: 9cd7f8669a59c6096331229df2e2ad87e628abab

manifest

@@ -1,5 +1,5 @@
-C Add\sthe\ssqlite3_next_stmt()\sinterface,\sincluding\stest\scases.\s(CVS\s5243)
+C Shuffle\ssome\sof\sthe\smutex\srelated\sdocumentation\sin\ssqlite.h.in\sto\smatch\sthe\snew\ssqlite3_mutex_methods\sbased\sAPI.\s(CVS\s5244)
-D 2008-06-19T02:52:25
+D 2008-06-19T08:51:24
 F Makefile.arm-wince-mingw32ce-gcc ac5f7b2cef0cd850d6f755ba6ee4ab961b1fadf7
 F Makefile.in ff6f90048555a0088f6a4b7406bed5e55a7c4eff
 F Makefile.linux-gcc d53183f4aa6a9192d249731c90dbdffbd2c68654
@@ -123,11 +123,11 @@ F src/mem2.c 23f9538f35fbcd5665afe7056a56be0c7ed65aa7
 F src/mem3.c 28b4812b87470a00b11821fb5850e7cabcce06c6
 F src/mem4.c 6703adb1717b26d9d70a1c2586b4b7b7ffee7909
 F src/mem5.c ad31a0a481b86b86f4ac0b6d952e69727d4e113a
-F src/mutex.c 67393ac4e82d2ff09622ec33b9f289deb9d8825e
+F src/mutex.c a485a0eac8ee2cd95f66e565b4c6696c18db968f
 F src/mutex.h 236677b27760d85701b5872d01b5cafedde5f0a9
-F src/mutex_os2.c d9eb88ad198c59f1a45d90b597c258562a40e52c
+F src/mutex_os2.c 7c948174d31e06df3e3dd0ef734691e95e30a5f4
-F src/mutex_unix.c 469a35c105435794375d683f75cad9e848817d19
+F src/mutex_unix.c 630a3860703ebcda94e99d179dc4ef4824489470
-F src/mutex_w32.c e03baa369c5e8e7ea4dd2e5b3d098e047f7a2f06
+F src/mutex_w32.c 36841fbd4450bf5b9dd5b065f2b614d3b50c7021
 F src/os.c e9f37351dc4aacc4861f0adbe463f21c8f5969fa
 F src/os.h c9a7f94e80193fd4cf27f5c5698eb56753f1b05a
 F src/os_common.h 24525d8b7bce66c374dfc1810a6c9043f3359b60
@@ -143,7 +143,7 @@ F src/printf.c 8b063da9dcde26b7c500a01444b718d86f21bc6e
 F src/random.c 5c754319d38abdd6acd74601ee0105504adc508a
 F src/select.c 669687459e7d0193c89de06c5dbed55b4a41191c
 F src/shell.c a12ea645271b7876c8f080146f48e20b00d367ec
-F src/sqlite.h.in 2590420afe3c9c5a05ee7269f32c3c6f4b06c053
+F src/sqlite.h.in cc64323ecc21320692c12726102976689ee5ae53
 F src/sqlite3ext.h faacd0e6a81aabee0861c6d7883c9172e74ef5b3
 F src/sqliteInt.h 6dd55232e738a4dac23475cd4b0e444dff75c896
 F src/sqliteLimit.h f435e728c6b620ef7312814d660a81f9356eb5c8
@@ -168,7 +168,7 @@ F src/test_hexio.c 2f1122aa3f012fa0142ee3c36ce5c902a70cd12f
 F src/test_loadext.c 22065d601a18878e5542191001f0eaa5d77c0ed8
 F src/test_malloc.c dc6d256544b1be96312367b24b93a778de8afdfe
 F src/test_md5.c 28209a4e2068711b5443c33104fe41f21d160071
-F src/test_mutex.c 08640d7547bfadb6997a22d72e63914feaf4bc4f
+F src/test_mutex.c 8cfe5c56d5583e07c25c50f59c42ca0104dd24bb
 F src/test_onefile.c 1f87d4a21cbfb24a7c35e4333fa0bd34d641f68d
 F src/test_osinst.c 867f1317bd135f942a63eab5a78da40fc70d1493
 F src/test_schema.c e3f93725f7c5b2cff84a69dc4332040dfbc8f81a
@@ -599,7 +599,7 @@ F tool/speedtest16.c c8a9c793df96db7e4933f0852abb7a03d48f2e81
 F tool/speedtest2.tcl ee2149167303ba8e95af97873c575c3e0fab58ff
 F tool/speedtest8.c 1dbced29de5f59ba2ebf877edcadf171540374d1
 F tool/speedtest8inst1.c 293327bc76823f473684d589a8160bde1f52c14e
-P eec9a54dc3554a00ea69fc8e26d205f30a3bcabd
+P 565a530896b40790287eeaad709edd51980fbddf
-R c8ee455d2762ac91cbcc6d328820d18d
+R 950854b62a7a587d35382e80a0549a75
-U drh
+U danielk1977
-Z 1aaf0ee87bfe5a8385c7655d6421e7d4
+Z 2b8089afd328ee7a65250c0132b39dd9

manifest.uuid

@@ -1 +1 @@
-565a530896b40790287eeaad709edd51980fbddf
+9cd7f8669a59c6096331229df2e2ad87e628abab

src/mutex.c

@@ -19,7 +19,7 @@
 ** implementation is suitable for testing.
 ** debugging purposes
 **
-** $Id: mutex.c,v 1.26 2008/06/18 18:57:42 danielk1977 Exp $
+** $Id: mutex.c,v 1.27 2008/06/19 08:51:24 danielk1977 Exp $
 */
 #include "sqliteInt.h"
 
@@ -257,12 +257,12 @@ static void noopMutexLeave(sqlite3_mutex *p){
 sqlite3_mutex_methods *sqlite3DefaultMutex(void){
   static sqlite3_mutex_methods sMutex = {
     noopMutexInit,
+    noopMutexEnd,
     noopMutexAlloc,
     noopMutexFree,
     noopMutexEnter,
     noopMutexTry,
     noopMutexLeave,
-    noopMutexEnd,
 
     noopMutexHeld,
     noopMutexNotheld

src/mutex_os2.c

@@ -11,7 +11,7 @@
 *************************************************************************
 ** This file contains the C functions that implement mutexes for OS/2
 **
-** $Id: mutex_os2.c,v 1.8 2008/06/18 21:08:16 pweilbacher Exp $
+** $Id: mutex_os2.c,v 1.9 2008/06/19 08:51:24 danielk1977 Exp $
 */
 #include "sqliteInt.h"
 
@@ -254,12 +254,12 @@ int os2MutexNotheld(sqlite3_mutex *p){
 sqlite3_mutex_methods *sqlite3DefaultMutex(void){
   static sqlite3_mutex_methods sMutex = {
     os2MutexInit,
+    os2MutexEnd,
     os2MutexAlloc,
     os2MutexFree,
     os2MutexEnter,
     os2MutexTry,
     os2MutexLeave,
-    os2MutexEnd,
 
     os2MutexHeld,
     os2MutexNotheld

src/mutex_unix.c

@@ -11,7 +11,7 @@
 *************************************************************************
 ** This file contains the C functions that implement mutexes for pthreads
 **
-** $Id: mutex_unix.c,v 1.10 2008/06/18 09:45:56 danielk1977 Exp $
+** $Id: mutex_unix.c,v 1.11 2008/06/19 08:51:24 danielk1977 Exp $
 */
 #include "sqliteInt.h"
 
@@ -307,12 +307,12 @@ static void pthreadMutexLeave(sqlite3_mutex *p){
 sqlite3_mutex_methods *sqlite3DefaultMutex(void){
   static sqlite3_mutex_methods sMutex = {
     pthreadMutexInit,
+    pthreadMutexEnd,
     pthreadMutexAlloc,
     pthreadMutexFree,
     pthreadMutexEnter,
     pthreadMutexTry,
     pthreadMutexLeave,
-    pthreadMutexEnd,
 
     pthreadMutexHeld,
     pthreadMutexNotheld

src/mutex_w32.c

@@ -11,7 +11,7 @@
 *************************************************************************
 ** This file contains the C functions that implement mutexes for win32
 **
-** $Id: mutex_w32.c,v 1.8 2008/06/17 17:21:18 danielk1977 Exp $
+** $Id: mutex_w32.c,v 1.9 2008/06/19 08:51:24 danielk1977 Exp $
 */
 #include "sqliteInt.h"
 
@@ -224,12 +224,12 @@ static void winMutexLeave(sqlite3_mutex *p){
 sqlite3_mutex_methods *sqlite3DefaultMutex(void){
   static sqlite3_mutex_methods sMutex = {
     winMutexInit,
+    winMutexEnd,
     winMutexAlloc,
     winMutexFree,
     winMutexEnter,
     winMutexTry,
     winMutexLeave,
-    winMutexEnd,
 
     winMutexHeld,
     winMutexNotheld

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.338 2008/06/19 02:52:25 drh Exp $
+** @(#) $Id: sqlite.h.in,v 1.339 2008/06/19 08:51:24 danielk1977 Exp $
 */
 #ifndef _SQLITE3_H_
 #define _SQLITE3_H_
@@ -5755,7 +5755,7 @@ int sqlite3_vfs_unregister(sqlite3_vfs*);
 ** CAPI3REF: Mutexes {F17000}
 **
 ** The SQLite core uses these routines for thread
-** synchronization.  Though they are intended for internal
+** synchronization. Though they are intended for internal
 ** use by SQLite, code that links against SQLite is
 ** permitted to use any of these routines.
 **
@@ -5779,24 +5779,11 @@ int sqlite3_vfs_unregister(sqlite3_vfs*);
 ** 
 ** If SQLite is compiled with the SQLITE_MUTEX_APPDEF preprocessor
 ** macro defined (with "-DSQLITE_MUTEX_APPDEF=1"), then no mutex
-** implementation is included with the library.  The
+** implementation is included with the library. In this case the
-** mutex interface routines defined here become external
+** application must supply a custom mutex implementation using the
-** references in the SQLite library for which implementations
+** [SQLITE_CONFIG_MUTEX] option of the sqlite3_config() function
-** must be provided by the application.  This facility allows an
+** before calling sqlite3_initialize() or any other public sqlite3_ 
-** application that links against SQLite to provide its own mutex
+** function that calls sqlite3_initialize().
-** implementation without having to modify the SQLite core.
-**
-** {F17001} The sqlite3_mutex_init() routine is called once by each
-** effective call to [sqlite3_initialize()].  The sqlite3_mutex_init()
-** interface initializes the mutex subsystem.  The application should
-** never call sqlite3_mutex_init() directly but only indirectly by
-** invoking [sqlite3_initialize()].
-**
-** {F17003} The sqlite3_mutex_end() routine undoes the effect of
-** sqlite3_mutex_init().  The sqlite3_mutex_end() interface is called
-** by [sqlite3_shutdown()].  The application should never call 
-** sqlite3_mutex_end() directly but only indirectly through
-** [sqlite3_shutdown()].
 **
 ** {F17011} The sqlite3_mutex_alloc() routine allocates a new
 ** mutex and returns a pointer to it. {F17012} If it returns NULL
@@ -5886,32 +5873,61 @@ void sqlite3_mutex_leave(sqlite3_mutex*);
 ** CAPI3REF: Mutex Methods Object {F17120}
 **
 ** An instance of this structure defines the low-level routines
-** used to allocate and use mutexes.  This structure is used as
+** used to allocate and use mutexes.
-** an argument to the [SQLITE_CONFIG_MUTEX] and [SQLITE_CONFIG_GETMUTEX]
+**
-** options of [sqlite3_config()].  The methods defined by this
+** Usually, the default mutex implementations provided by SQLite are
-** structure implement the following interfaces (respectively):
+** sufficient, however the user has the option of substituting a custom 
+** implementation for specialized deployments or systems for which SQLite 
+** does not provide a suitable implementation. In this case, the user
+** creates and populates an instance of this structure to pass
+** to sqlite3_config() along with the [SQLITE_CONFIG_MUTEX] option. 
+** Additionally, an instance of this structure can be used as an
+** output variable when querying the system for the current mutex
+** implementation, using the [SQLITE_CONFIG_GETMUTEX] option.
+**
+** The xMutexInit method defined by this structure is invoked as
+** part of system initialization by the sqlite3_initialize() function.
+** {F17001} The xMutexInit routine shall be called by SQLite once for each
+** effective call to [sqlite3_initialize()].  
+**
+** The xMutexEnd method defined by this structure is invoked as
+** part of system shutdown by the sqlite3_shutdown() function. The
+** implementation of this method is expected to release all outstanding
+** resources obtained by the mutex methods implementation, especially
+** those obtained by the xMutexInit method. {F17003} The xMutexEnd() 
+** interface shall be invoked once for each call to [sqlite3_shutdown()]. 
+**
+** The remaining seven methods defined by this structure (xMutexAlloc,
+** xMutexFree, xMutexEnter, xMutexTry, xMutexLeave, xMutexHeld and
+** xMutexNotheld) implement the following interfaces (respectively):
 **
 ** <ul>
-** <li>  [sqlite3_mutex_init()] </li>
+**   <li>  [sqlite3_mutex_alloc()] </li>
-** <li>  [sqlite3_mutex_alloc()] </li>
+**   <li>  [sqlite3_mutex_free()] </li>
-** <li>  [sqlite3_mutex_free()] </li>
+**   <li>  [sqlite3_mutex_enter()] </li>
-** <li>  [sqlite3_mutex_enter()] </li>
+**   <li>  [sqlite3_mutex_try()] </li>
-** <li>  [sqlite3_mutex_try()] </li>
+**   <li>  [sqlite3_mutex_leave()] </li>
-** <li>  [sqlite3_mutex_leave()] </li>
+**   <li>  [sqlite3_mutex_held()] </li>
-** <li>  [sqlite3_mutex_end()] </li>
+**   <li>  [sqlite3_mutex_notheld()] </li>
-** <li>  [sqlite3_mutex_held()] </li>
-** <li>  [sqlite3_mutex_notheld()] </li>
 ** </ul>
+**
+** The only difference is that the public sqlite3_XXX functions enumerated
+** above silently ignore any invocations that pass a NULL pointer instead
+** of a valid mutex handle. The implementations of the methods defined
+** by this structure are not required to handle this case, the results
+** of passing a NULL pointer instead of a valid mutex handle are undefined
+** (i.e. it is acceptable to provide an implementation that segfaults if
+** it is passed a NULL pointer).
 */
 typedef struct sqlite3_mutex_methods sqlite3_mutex_methods;
 struct sqlite3_mutex_methods {
   int (*xMutexInit)(void);
+  int (*xMutexEnd)(void);
   sqlite3_mutex *(*xMutexAlloc)(int);
   void (*xMutexFree)(sqlite3_mutex *);
   void (*xMutexEnter)(sqlite3_mutex *);
   int (*xMutexTry)(sqlite3_mutex *);
   void (*xMutexLeave)(sqlite3_mutex *);
-  int (*xMutexEnd)(void);
   int (*xMutexHeld)(sqlite3_mutex *);
   int (*xMutexNotheld)(sqlite3_mutex *);
 };

src/test_mutex.c

@@ -10,7 +10,7 @@
 **
 *************************************************************************
 ** 
-** $Id: test_mutex.c,v 1.2 2008/06/18 17:09:10 danielk1977 Exp $
+** $Id: test_mutex.c,v 1.3 2008/06/19 08:51:25 danielk1977 Exp $
 */
 
 #include "tcl.h"
@@ -146,12 +146,12 @@ static int test_install_mutex_counters(
 
   sqlite3_mutex_methods counter_methods = {
     counterMutexInit,
+    counterMutexEnd,
     counterMutexAlloc,
     counterMutexFree,
     counterMutexEnter,
     counterMutexTry,
     counterMutexLeave,
-    counterMutexEnd,
     counterMutexHeld,
     counterMutexNotheld
   };