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