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