Clarify the conditions under which homegrown recursive mutexes work

(they require a coherent cache) and only enable them if there is an
explicit #define so as to avoid accidental use on platforms that do
not meet the constraints.  Ticket #2805. (CVS 4575)

FossilOrigin-Name: 80299eebddba9aac4c1bc36ffa2b440bffbf1751

3 files changed, 19 insertions, 13 deletions

diff --git a/manifest b/manifest
index f4b976cf7..e8fe5bc7c 100644
--- a/manifest
+++ b/manifest
@@ -1,5 +1,5 @@
-C Preset\sthe\slegacy_file_format\spragma\sto\sthe\svalue\sof\sthe\sprimary\ndatabase\sso\sthat\sa\sVACUUM\swill\snot\sunknowingly\salter\sthe\ssetting.\nTicket\s#2804.\s(CVS\s4574)
-D 2007-11-28T13:43:17
+C Clarify\sthe\sconditions\sunder\swhich\shomegrown\srecursive\smutexes\swork\n(they\srequire\sa\scoherent\scache)\sand\sonly\senable\sthem\sif\sthere\sis\san\nexplicit\s#define\sso\sas\sto\savoid\saccidental\suse\son\splatforms\sthat\sdo\nnot\smeet\sthe\sconstraints.\s\sTicket\s#2805.\s(CVS\s4575)
+D 2007-11-28T13:55:55
 F Makefile.arm-wince-mingw32ce-gcc ac5f7b2cef0cd850d6f755ba6ee4ab961b1fadf7
 F Makefile.in 35396fd58890420b29edcf27b6c0e2d054862a6b
 F Makefile.linux-gcc d53183f4aa6a9192d249731c90dbdffbd2c68654
@@ -110,7 +110,7 @@ F src/mem3.c a9857cf92c9e4c889184b2cf1ca1839c801fc942
 F src/mutex.c 3259f62c2429967aee6dc112117a6d2f499ef061
 F src/mutex.h 079fa6fe9da18ceb89e79012c010594c6672addb
 F src/mutex_os2.c 7fe4773e98ed74a63b2e54fc557929eb155f6269
-F src/mutex_unix.c 69e996b7c26bb50619c79c173dbba21658b65d2f
+F src/mutex_unix.c 94da6981f99f541fa712eae2394a02abe28d8d81
 F src/mutex_w32.c 6e197765f283815496193e78e9548b5d0e53b68e
 F src/os.c 8360932f1450b2b45edb608a3b184b031f7d00cc
 F src/os.h b75506ab40d222300f38023acb56fe08df5ffe33
@@ -593,7 +593,7 @@ F www/tclsqlite.tcl 8be95ee6dba05eabcd27a9d91331c803f2ce2130
 F www/vdbe.tcl 87a31ace769f20d3627a64fa1fade7fed47b90d0
 F www/version3.tcl 890248cf7b70e60c383b0e84d77d5132b3ead42b
 F www/whentouse.tcl fc46eae081251c3c181bd79c5faef8195d7991a5
-P f366a776c1b2dda42b4f10fdb8be66029165d084
-R f8726377bf1d2f12ba17ef1e3030e09a
+P f731fa6bb398d8af621af17dc0677dd0f715c4a7
+R 4e1efce73c2c2dbd0b0a966f60aca236
 U drh
-Z 4b43ff400d6268b573f303c0eaf9af93
+Z e8231964a01316a62ce8f3b57c4b7533
diff --git a/manifest.uuid b/manifest.uuid
index 51af5f61a..bf26b8587 100644
--- a/manifest.uuid
+++ b/manifest.uuid
@@ -1 +1 @@
-f731fa6bb398d8af621af17dc0677dd0f715c4a7
\ No newline at end of file
+80299eebddba9aac4c1bc36ffa2b440bffbf1751
\ No newline at end of file
diff --git a/src/mutex_unix.c b/src/mutex_unix.c
index 20a4e0ea7..4b7971bc8 100644
--- a/src/mutex_unix.c
+++ b/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.3 2007/11/28 00:51:35 drh Exp $
+** $Id: mutex_unix.c,v 1.4 2007/11/28 13:55:55 drh Exp $
 */
 #include "sqliteInt.h"
 
@@ -94,7 +94,7 @@ sqlite3_mutex *sqlite3_mutex_alloc(int iType){
     case SQLITE_MUTEX_RECURSIVE: {
       p = sqlite3MallocZero( sizeof(*p) );
       if( p ){
-#ifdef PTHREAD_MUTEX_RECURSIVE
+#ifndef SQLITE_HOMEGROWN_RECURSIVE_MUTEX
         /* Use a recursive mutex if it is available */
         pthread_mutexattr_t recursiveAttr;
         pthread_mutexattr_init(&recursiveAttr);
@@ -158,9 +158,8 @@ void sqlite3_mutex_enter(sqlite3_mutex *p){
   assert( p );
   assert( p->id==SQLITE_MUTEX_RECURSIVE || sqlite3_mutex_notheld(p) );
 
-#ifdef PTHREAD_MUTEX_RECURSIVE
+#ifndef SQLITE_HOMEGROWN_RECURSIVE_MUTEX
   /* Use the built-in recursive mutexes if they are available.
-  ** That they are not available on all systems.
   */
   pthread_mutex_lock(&p->mutex);
   p->owner = pthread_self();
@@ -171,6 +170,10 @@ void sqlite3_mutex_enter(sqlite3_mutex *p){
   ** is atomic - that it cannot be deceived into thinking self
   ** and p->owner are equal if p->owner changes between two values
   ** that are not equal to self while the comparison is taking place.
+  ** This implementation also assumes a coherent cache - that 
+  ** separate processes cannot read different values from the same
+  ** address at the same time.  If either of these two conditions
+  ** are not met, then the mutexes will fail and problems will result.
   */
   {
     pthread_t self = pthread_self();
@@ -196,9 +199,8 @@ int sqlite3_mutex_try(sqlite3_mutex *p){
   assert( p );
   assert( p->id==SQLITE_MUTEX_RECURSIVE || sqlite3_mutex_notheld(p) );
 
-#ifdef PTHREAD_MUTEX_RECURSIVE
+#ifndef SQLITE_HOMEGROWN_RECURSIVE_MUTEX
   /* Use the built-in recursive mutexes if they are available.
-  ** That they are not available on all systems.
   */
   if( pthread_mutex_trylock(&p->mutex)==0 ){
     p->owner = pthread_self();
@@ -213,6 +215,10 @@ int sqlite3_mutex_try(sqlite3_mutex *p){
   ** is atomic - that it cannot be deceived into thinking self
   ** and p->owner are equal if p->owner changes between two values
   ** that are not equal to self while the comparison is taking place.
+  ** This implementation also assumes a coherent cache - that 
+  ** separate processes cannot read different values from the same
+  ** address at the same time.  If either of these two conditions
+  ** are not met, then the mutexes will fail and problems will result.
   */
   {
     pthread_t self = pthread_self();