third_party/sqlite/sqlite-src-3080704/src/mutex_unix.c

   1 /*
   2 ** 2007 August 28
   3 **
   4 ** The author disclaims copyright to this source code.  In place of
   5 ** a legal notice, here is a blessing:
   6 **
   7 **    May you do good and not evil.
   8 **    May you find forgiveness for yourself and forgive others.
   9 **    May you share freely, never taking more than you give.
  10 **
  11 *************************************************************************
  12 ** This file contains the C functions that implement mutexes for pthreads
  13 */
  14 #include "sqliteInt.h"
  15
  16 /*
  17 ** The code in this file is only used if we are compiling threadsafe
  18 ** under unix with pthreads.
  19 **
  20 ** Note that this implementation requires a version of pthreads that
  21 ** supports recursive mutexes.
  22 */
  23 #ifdef SQLITE_MUTEX_PTHREADS
  24
  25 #include <pthread.h>
  26
  27 /*
  28 ** The sqlite3_mutex.id, sqlite3_mutex.nRef, and sqlite3_mutex.owner fields
  29 ** are necessary under two condidtions:  (1) Debug builds and (2) using
  30 ** home-grown mutexes.  Encapsulate these conditions into a single #define.
  31 */
  32 #if defined(SQLITE_DEBUG) || defined(SQLITE_HOMEGROWN_RECURSIVE_MUTEX)
  33 # define SQLITE_MUTEX_NREF 1
  34 #else
  35 # define SQLITE_MUTEX_NREF 0
  36 #endif
  37
  38 /*
  39 ** Each recursive mutex is an instance of the following structure.
  40 */
  41 struct sqlite3_mutex {
  42   pthread_mutex_t mutex;     /* Mutex controlling the lock */
  43 #if SQLITE_MUTEX_NREF
  44   int id;                    /* Mutex type */
  45   volatile int nRef;         /* Number of entrances */
  46   volatile pthread_t owner;  /* Thread that is within this mutex */
  47   int trace;                 /* True to trace changes */
  48 #endif
  49 };
  50 #if SQLITE_MUTEX_NREF
  51 #define SQLITE3_MUTEX_INITIALIZER { PTHREAD_MUTEX_INITIALIZER, 0, 0, (pthread_t)0, 0 }
  52 #else
  53 #define SQLITE3_MUTEX_INITIALIZER { PTHREAD_MUTEX_INITIALIZER }
  54 #endif
  55
  56 /*
  57 ** The sqlite3_mutex_held() and sqlite3_mutex_notheld() routine are
  58 ** intended for use only inside assert() statements.  On some platforms,
  59 ** there might be race conditions that can cause these routines to
  60 ** deliver incorrect results.  In particular, if pthread_equal() is
  61 ** not an atomic operation, then these routines might delivery
  62 ** incorrect results.  On most platforms, pthread_equal() is a
  63 ** comparison of two integers and is therefore atomic.  But we are
  64 ** told that HPUX is not such a platform.  If so, then these routines
  65 ** will not always work correctly on HPUX.
  66 **
  67 ** On those platforms where pthread_equal() is not atomic, SQLite
  68 ** should be compiled without -DSQLITE_DEBUG and with -DNDEBUG to
  69 ** make sure no assert() statements are evaluated and hence these
  70 ** routines are never called.
  71 */
  72 #if !defined(NDEBUG) || defined(SQLITE_DEBUG)
  73 static int pthreadMutexHeld(sqlite3_mutex *p){
  74   return (p->nRef!=0 && pthread_equal(p->owner, pthread_self()));
  75 }
  76 static int pthreadMutexNotheld(sqlite3_mutex *p){
  77   return p->nRef==0 || pthread_equal(p->owner, pthread_self())==0;
  78 }
  79 #endif
  80
  81 /*
  82 ** Initialize and deinitialize the mutex subsystem.
  83 */
  84 static int pthreadMutexInit(void){ return SQLITE_OK; }
  85 static int pthreadMutexEnd(void){ return SQLITE_OK; }
  86
  87 /*
  88 ** The sqlite3_mutex_alloc() routine allocates a new
  89 ** mutex and returns a pointer to it.  If it returns NULL
  90 ** that means that a mutex could not be allocated.  SQLite
  91 ** will unwind its stack and return an error.  The argument
  92 ** to sqlite3_mutex_alloc() is one of these integer constants:
  93 **
  94 ** <ul>
  95 ** <li>  SQLITE_MUTEX_FAST
  96 ** <li>  SQLITE_MUTEX_RECURSIVE
  97 ** <li>  SQLITE_MUTEX_STATIC_MASTER
  98 ** <li>  SQLITE_MUTEX_STATIC_MEM
  99 ** <li>  SQLITE_MUTEX_STATIC_OPEN
 100 ** <li>  SQLITE_MUTEX_STATIC_PRNG
 101 ** <li>  SQLITE_MUTEX_STATIC_LRU
 102 ** <li>  SQLITE_MUTEX_STATIC_PMEM
 103 ** <li>  SQLITE_MUTEX_STATIC_APP1
 104 ** <li>  SQLITE_MUTEX_STATIC_APP2
 105 ** <li>  SQLITE_MUTEX_STATIC_APP3
 106 ** </ul>
 107 **
 108 ** The first two constants cause sqlite3_mutex_alloc() to create
 109 ** a new mutex.  The new mutex is recursive when SQLITE_MUTEX_RECURSIVE
 110 ** is used but not necessarily so when SQLITE_MUTEX_FAST is used.
 111 ** The mutex implementation does not need to make a distinction
 112 ** between SQLITE_MUTEX_RECURSIVE and SQLITE_MUTEX_FAST if it does
 113 ** not want to.  But SQLite will only request a recursive mutex in
 114 ** cases where it really needs one.  If a faster non-recursive mutex
 115 ** implementation is available on the host platform, the mutex subsystem
 116 ** might return such a mutex in response to SQLITE_MUTEX_FAST.
 117 **
 118 ** The other allowed parameters to sqlite3_mutex_alloc() each return
 119 ** a pointer to a static preexisting mutex.  Six static mutexes are
 120 ** used by the current version of SQLite.  Future versions of SQLite
 121 ** may add additional static mutexes.  Static mutexes are for internal
 122 ** use by SQLite only.  Applications that use SQLite mutexes should
 123 ** use only the dynamic mutexes returned by SQLITE_MUTEX_FAST or
 124 ** SQLITE_MUTEX_RECURSIVE.
 125 **
 126 ** Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST
 127 ** or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc()
 128 ** returns a different mutex on every call.  But for the static
 129 ** mutex types, the same mutex is returned on every call that has
 130 ** the same type number.
 131 */
 132 static sqlite3_mutex *pthreadMutexAlloc(int iType){
 133   static sqlite3_mutex staticMutexes[] = {
 134     SQLITE3_MUTEX_INITIALIZER,
 135     SQLITE3_MUTEX_INITIALIZER,
 136     SQLITE3_MUTEX_INITIALIZER,
 137     SQLITE3_MUTEX_INITIALIZER,
 138     SQLITE3_MUTEX_INITIALIZER,
 139     SQLITE3_MUTEX_INITIALIZER,
 140     SQLITE3_MUTEX_INITIALIZER,
 141     SQLITE3_MUTEX_INITIALIZER,
 142     SQLITE3_MUTEX_INITIALIZER
 143   };
 144   sqlite3_mutex *p;
 145   switch( iType ){
 146     case SQLITE_MUTEX_RECURSIVE: {
 147       p = sqlite3MallocZero( sizeof(*p) );
 148       if( p ){
 149 #ifdef SQLITE_HOMEGROWN_RECURSIVE_MUTEX
 150         /* If recursive mutexes are not available, we will have to
 151         ** build our own.  See below. */
 152         pthread_mutex_init(&p->mutex, 0);
 153 #else
 154         /* Use a recursive mutex if it is available */
 155         pthread_mutexattr_t recursiveAttr;
 156         pthread_mutexattr_init(&recursiveAttr);
 157         pthread_mutexattr_settype(&recursiveAttr, PTHREAD_MUTEX_RECURSIVE);
 158         pthread_mutex_init(&p->mutex, &recursiveAttr);
 159         pthread_mutexattr_destroy(&recursiveAttr);
 160 #endif
 161 #if SQLITE_MUTEX_NREF
 162         p->id = iType;
 163 #endif
 164       }
 165       break;
 166     }
 167     case SQLITE_MUTEX_FAST: {
 168       p = sqlite3MallocZero( sizeof(*p) );
 169       if( p ){
 170 #if SQLITE_MUTEX_NREF
 171         p->id = iType;
 172 #endif
 173         pthread_mutex_init(&p->mutex, 0);
 174       }
 175       break;
 176     }
 177     default: {
 178       assert( iType-2 >= 0 );
 179       assert( iType-2 < ArraySize(staticMutexes) );
 180       p = &staticMutexes[iType-2];
 181 #if SQLITE_MUTEX_NREF
 182       p->id = iType;
 183 #endif
 184       break;
 185     }
 186   }
 187   return p;
 188 }
 189
 190
 191 /*
 192 ** This routine deallocates a previously
 193 ** allocated mutex.  SQLite is careful to deallocate every
 194 ** mutex that it allocates.
 195 */
 196 static void pthreadMutexFree(sqlite3_mutex *p){
 197   assert( p->nRef==0 );
 198   assert( p->id==SQLITE_MUTEX_FAST || p->id==SQLITE_MUTEX_RECURSIVE );
 199   pthread_mutex_destroy(&p->mutex);
 200   sqlite3_free(p);
 201 }
 202
 203 /*
 204 ** The sqlite3_mutex_enter() and sqlite3_mutex_try() routines attempt
 205 ** to enter a mutex.  If another thread is already within the mutex,
 206 ** sqlite3_mutex_enter() will block and sqlite3_mutex_try() will return
 207 ** SQLITE_BUSY.  The sqlite3_mutex_try() interface returns SQLITE_OK
 208 ** upon successful entry.  Mutexes created using SQLITE_MUTEX_RECURSIVE can
 209 ** be entered multiple times by the same thread.  In such cases the,
 210 ** mutex must be exited an equal number of times before another thread
 211 ** can enter.  If the same thread tries to enter any other kind of mutex
 212 ** more than once, the behavior is undefined.
 213 */
 214 static void pthreadMutexEnter(sqlite3_mutex *p){
 215   assert( p->id==SQLITE_MUTEX_RECURSIVE || pthreadMutexNotheld(p) );
 216
 217 #ifdef SQLITE_HOMEGROWN_RECURSIVE_MUTEX
 218   /* If recursive mutexes are not available, then we have to grow
 219   ** our own.  This implementation assumes that pthread_equal()
 220   ** is atomic - that it cannot be deceived into thinking self
 221   ** and p->owner are equal if p->owner changes between two values
 222   ** that are not equal to self while the comparison is taking place.
 223   ** This implementation also assumes a coherent cache - that
 224   ** separate processes cannot read different values from the same
 225   ** address at the same time.  If either of these two conditions
 226   ** are not met, then the mutexes will fail and problems will result.
 227   */
 228   {
 229     pthread_t self = pthread_self();
 230     if( p->nRef>0 && pthread_equal(p->owner, self) ){
 231       p->nRef++;
 232     }else{
 233       pthread_mutex_lock(&p->mutex);
 234       assert( p->nRef==0 );
 235       p->owner = self;
 236       p->nRef = 1;
 237     }
 238   }
 239 #else
 240   /* Use the built-in recursive mutexes if they are available.
 241   */
 242   pthread_mutex_lock(&p->mutex);
 243 #if SQLITE_MUTEX_NREF
 244   assert( p->nRef>0 || p->owner==0 );
 245   p->owner = pthread_self();
 246   p->nRef++;
 247 #endif
 248 #endif
 249
 250 #ifdef SQLITE_DEBUG
 251   if( p->trace ){
 252     printf("enter mutex %p (%d) with nRef=%d\n", p, p->trace, p->nRef);
 253   }
 254 #endif
 255 }
 256 static int pthreadMutexTry(sqlite3_mutex *p){
 257   int rc;
 258   assert( p->id==SQLITE_MUTEX_RECURSIVE || pthreadMutexNotheld(p) );
 259
 260 #ifdef SQLITE_HOMEGROWN_RECURSIVE_MUTEX
 261   /* If recursive mutexes are not available, then we have to grow
 262   ** our own.  This implementation assumes that pthread_equal()
 263   ** is atomic - that it cannot be deceived into thinking self
 264   ** and p->owner are equal if p->owner changes between two values
 265   ** that are not equal to self while the comparison is taking place.
 266   ** This implementation also assumes a coherent cache - that
 267   ** separate processes cannot read different values from the same
 268   ** address at the same time.  If either of these two conditions
 269   ** are not met, then the mutexes will fail and problems will result.
 270   */
 271   {
 272     pthread_t self = pthread_self();
 273     if( p->nRef>0 && pthread_equal(p->owner, self) ){
 274       p->nRef++;
 275       rc = SQLITE_OK;
 276     }else if( pthread_mutex_trylock(&p->mutex)==0 ){
 277       assert( p->nRef==0 );
 278       p->owner = self;
 279       p->nRef = 1;
 280       rc = SQLITE_OK;
 281     }else{
 282       rc = SQLITE_BUSY;
 283     }
 284   }
 285 #else
 286   /* Use the built-in recursive mutexes if they are available.
 287   */
 288   if( pthread_mutex_trylock(&p->mutex)==0 ){
 289 #if SQLITE_MUTEX_NREF
 290     p->owner = pthread_self();
 291     p->nRef++;
 292 #endif
 293     rc = SQLITE_OK;
 294   }else{
 295     rc = SQLITE_BUSY;
 296   }
 297 #endif
 298
 299 #ifdef SQLITE_DEBUG
 300   if( rc==SQLITE_OK && p->trace ){
 301     printf("enter mutex %p (%d) with nRef=%d\n", p, p->trace, p->nRef);
 302   }
 303 #endif
 304   return rc;
 305 }
 306
 307 /*
 308 ** The sqlite3_mutex_leave() routine exits a mutex that was
 309 ** previously entered by the same thread.  The behavior
 310 ** is undefined if the mutex is not currently entered or
 311 ** is not currently allocated.  SQLite will never do either.
 312 */
 313 static void pthreadMutexLeave(sqlite3_mutex *p){
 314   assert( pthreadMutexHeld(p) );
 315 #if SQLITE_MUTEX_NREF
 316   p->nRef--;
 317   if( p->nRef==0 ) p->owner = 0;
 318 #endif
 319   assert( p->nRef==0 || p->id==SQLITE_MUTEX_RECURSIVE );
 320
 321 #ifdef SQLITE_HOMEGROWN_RECURSIVE_MUTEX
 322   if( p->nRef==0 ){
 323     pthread_mutex_unlock(&p->mutex);
 324   }
 325 #else
 326   pthread_mutex_unlock(&p->mutex);
 327 #endif
 328
 329 #ifdef SQLITE_DEBUG
 330   if( p->trace ){
 331     printf("leave mutex %p (%d) with nRef=%d\n", p, p->trace, p->nRef);
 332   }
 333 #endif
 334 }
 335
 336 sqlite3_mutex_methods const *sqlite3DefaultMutex(void){
 337   static const sqlite3_mutex_methods sMutex = {
 338     pthreadMutexInit,
 339     pthreadMutexEnd,
 340     pthreadMutexAlloc,
 341     pthreadMutexFree,
 342     pthreadMutexEnter,
 343     pthreadMutexTry,
 344     pthreadMutexLeave,
 345 #ifdef SQLITE_DEBUG
 346     pthreadMutexHeld,
 347     pthreadMutexNotheld
 348 #else
 349     0,
 350     0
 351 #endif
 352   };
 353
 354   return &sMutex;
 355 }
 356
 357 #endif /* SQLITE_MUTEX_PTHREADS */