src/mutex_w32.c

   1 /*
   2 ** 2007 August 14
   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 win32
  13 */
  14 #include "sqliteInt.h"
  15
  16 /*
  17 ** The code in this file is only used if we are compiling multithreaded
  18 ** on a win32 system.
  19 */
  20 #ifdef SQLITE_MUTEX_W32
  21
  22 /*
  23 ** Each recursive mutex is an instance of the following structure.
  24 */
  25 struct sqlite3_mutex {
  26   CRITICAL_SECTION mutex;    /* Mutex controlling the lock */
  27   int id;                    /* Mutex type */
  28 #ifdef SQLITE_DEBUG
  29   volatile int nRef;         /* Number of enterances */
  30   volatile DWORD owner;      /* Thread holding this mutex */
  31   int trace;                 /* True to trace changes */
  32 #endif
  33 };
  34 #define SQLITE_W32_MUTEX_INITIALIZER { 0 }
  35 #ifdef SQLITE_DEBUG
  36 #define SQLITE3_MUTEX_INITIALIZER { SQLITE_W32_MUTEX_INITIALIZER, 0, 0L, (DWORD)0, 0 }
  37 #else
  38 #define SQLITE3_MUTEX_INITIALIZER { SQLITE_W32_MUTEX_INITIALIZER, 0 }
  39 #endif
  40
  41 /*
  42 ** Return true (non-zero) if we are running under WinNT, Win2K, WinXP,
  43 ** or WinCE.  Return false (zero) for Win95, Win98, or WinME.
  44 **
  45 ** Here is an interesting observation:  Win95, Win98, and WinME lack
  46 ** the LockFileEx() API.  But we can still statically link against that
  47 ** API as long as we don't call it win running Win95/98/ME.  A call to
  48 ** this routine is used to determine if the host is Win95/98/ME or
  49 ** WinNT/2K/XP so that we will know whether or not we can safely call
  50 ** the LockFileEx() API.
  51 **
  52 ** mutexIsNT() is only used for the TryEnterCriticalSection() API call,
  53 ** which is only available if your application was compiled with
  54 ** _WIN32_WINNT defined to a value >= 0x0400.  Currently, the only
  55 ** call to TryEnterCriticalSection() is #ifdef'ed out, so #ifdef
  56 ** this out as well.
  57 */
  58 #if 0
  59 #if SQLITE_OS_WINCE || SQLITE_OS_WINRT
  60 # define mutexIsNT()  (1)
  61 #else
  62   static int mutexIsNT(void){
  63     static int osType = 0;
  64     if( osType==0 ){
  65       OSVERSIONINFO sInfo;
  66       sInfo.dwOSVersionInfoSize = sizeof(sInfo);
  67       GetVersionEx(&sInfo);
  68       osType = sInfo.dwPlatformId==VER_PLATFORM_WIN32_NT ? 2 : 1;
  69     }
  70     return osType==2;
  71   }
  72 #endif /* SQLITE_OS_WINCE || SQLITE_OS_WINRT */
  73 #endif
  74
  75 #ifdef SQLITE_DEBUG
  76 /*
  77 ** The sqlite3_mutex_held() and sqlite3_mutex_notheld() routine are
  78 ** intended for use only inside assert() statements.
  79 */
  80 static int winMutexHeld(sqlite3_mutex *p){
  81   return p->nRef!=0 && p->owner==GetCurrentThreadId();
  82 }
  83 static int winMutexNotheld2(sqlite3_mutex *p, DWORD tid){
  84   return p->nRef==0 || p->owner!=tid;
  85 }
  86 static int winMutexNotheld(sqlite3_mutex *p){
  87   DWORD tid = GetCurrentThreadId();
  88   return winMutexNotheld2(p, tid);
  89 }
  90 #endif
  91
  92
  93 /*
  94 ** Initialize and deinitialize the mutex subsystem.
  95 */
  96 static sqlite3_mutex winMutex_staticMutexes[6] = {
  97   SQLITE3_MUTEX_INITIALIZER,
  98   SQLITE3_MUTEX_INITIALIZER,
  99   SQLITE3_MUTEX_INITIALIZER,
 100   SQLITE3_MUTEX_INITIALIZER,
 101   SQLITE3_MUTEX_INITIALIZER,
 102   SQLITE3_MUTEX_INITIALIZER
 103 };
 104 static int winMutex_isInit = 0;
 105 /* As winMutexInit() and winMutexEnd() are called as part
 106 ** of the sqlite3_initialize and sqlite3_shutdown()
 107 ** processing, the "interlocked" magic is probably not
 108 ** strictly necessary.
 109 */
 110 static LONG winMutex_lock = 0;
 111
 112 void sqlite3_win32_sleep(DWORD milliseconds); /* os_win.c */
 113
 114 static int winMutexInit(void){
 115   /* The first to increment to 1 does actual initialization */
 116   if( InterlockedCompareExchange(&winMutex_lock, 1, 0)==0 ){
 117     int i;
 118     for(i=0; i<ArraySize(winMutex_staticMutexes); i++){
 119 #if SQLITE_OS_WINRT
 120       InitializeCriticalSectionEx(&winMutex_staticMutexes[i].mutex, 0, 0);
 121 #else
 122       InitializeCriticalSection(&winMutex_staticMutexes[i].mutex);
 123 #endif
 124     }
 125     winMutex_isInit = 1;
 126   }else{
 127     /* Someone else is in the process of initing the static mutexes */
 128     while( !winMutex_isInit ){
 129       sqlite3_win32_sleep(1);
 130     }
 131   }
 132   return SQLITE_OK;
 133 }
 134
 135 static int winMutexEnd(void){
 136   /* The first to decrement to 0 does actual shutdown
 137   ** (which should be the last to shutdown.) */
 138   if( InterlockedCompareExchange(&winMutex_lock, 0, 1)==1 ){
 139     if( winMutex_isInit==1 ){
 140       int i;
 141       for(i=0; i<ArraySize(winMutex_staticMutexes); i++){
 142         DeleteCriticalSection(&winMutex_staticMutexes[i].mutex);
 143       }
 144       winMutex_isInit = 0;
 145     }
 146   }
 147   return SQLITE_OK;
 148 }
 149
 150 /*
 151 ** The sqlite3_mutex_alloc() routine allocates a new
 152 ** mutex and returns a pointer to it.  If it returns NULL
 153 ** that means that a mutex could not be allocated.  SQLite
 154 ** will unwind its stack and return an error.  The argument
 155 ** to sqlite3_mutex_alloc() is one of these integer constants:
 156 **
 157 ** <ul>
 158 ** <li>  SQLITE_MUTEX_FAST
 159 ** <li>  SQLITE_MUTEX_RECURSIVE
 160 ** <li>  SQLITE_MUTEX_STATIC_MASTER
 161 ** <li>  SQLITE_MUTEX_STATIC_MEM
 162 ** <li>  SQLITE_MUTEX_STATIC_MEM2
 163 ** <li>  SQLITE_MUTEX_STATIC_PRNG
 164 ** <li>  SQLITE_MUTEX_STATIC_LRU
 165 ** <li>  SQLITE_MUTEX_STATIC_PMEM
 166 ** </ul>
 167 **
 168 ** The first two constants cause sqlite3_mutex_alloc() to create
 169 ** a new mutex.  The new mutex is recursive when SQLITE_MUTEX_RECURSIVE
 170 ** is used but not necessarily so when SQLITE_MUTEX_FAST is used.
 171 ** The mutex implementation does not need to make a distinction
 172 ** between SQLITE_MUTEX_RECURSIVE and SQLITE_MUTEX_FAST if it does
 173 ** not want to.  But SQLite will only request a recursive mutex in
 174 ** cases where it really needs one.  If a faster non-recursive mutex
 175 ** implementation is available on the host platform, the mutex subsystem
 176 ** might return such a mutex in response to SQLITE_MUTEX_FAST.
 177 **
 178 ** The other allowed parameters to sqlite3_mutex_alloc() each return
 179 ** a pointer to a static preexisting mutex.  Six static mutexes are
 180 ** used by the current version of SQLite.  Future versions of SQLite
 181 ** may add additional static mutexes.  Static mutexes are for internal
 182 ** use by SQLite only.  Applications that use SQLite mutexes should
 183 ** use only the dynamic mutexes returned by SQLITE_MUTEX_FAST or
 184 ** SQLITE_MUTEX_RECURSIVE.
 185 **
 186 ** Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST
 187 ** or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc()
 188 ** returns a different mutex on every call.  But for the static
 189 ** mutex types, the same mutex is returned on every call that has
 190 ** the same type number.
 191 */
 192 static sqlite3_mutex *winMutexAlloc(int iType){
 193   sqlite3_mutex *p;
 194
 195   switch( iType ){
 196     case SQLITE_MUTEX_FAST:
 197     case SQLITE_MUTEX_RECURSIVE: {
 198       p = sqlite3MallocZero( sizeof(*p) );
 199       if( p ){
 200 #ifdef SQLITE_DEBUG
 201         p->id = iType;
 202 #endif
 203 #if SQLITE_OS_WINRT
 204         InitializeCriticalSectionEx(&p->mutex, 0, 0);
 205 #else
 206         InitializeCriticalSection(&p->mutex);
 207 #endif
 208       }
 209       break;
 210     }
 211     default: {
 212       assert( winMutex_isInit==1 );
 213       assert( iType-2 >= 0 );
 214       assert( iType-2 < ArraySize(winMutex_staticMutexes) );
 215       p = &winMutex_staticMutexes[iType-2];
 216 #ifdef SQLITE_DEBUG
 217       p->id = iType;
 218 #endif
 219       break;
 220     }
 221   }
 222   return p;
 223 }
 224
 225
 226 /*
 227 ** This routine deallocates a previously
 228 ** allocated mutex.  SQLite is careful to deallocate every
 229 ** mutex that it allocates.
 230 */
 231 static void winMutexFree(sqlite3_mutex *p){
 232   assert( p );
 233   assert( p->nRef==0 && p->owner==0 );
 234   assert( p->id==SQLITE_MUTEX_FAST || p->id==SQLITE_MUTEX_RECURSIVE );
 235   DeleteCriticalSection(&p->mutex);
 236   sqlite3_free(p);
 237 }
 238
 239 /*
 240 ** The sqlite3_mutex_enter() and sqlite3_mutex_try() routines attempt
 241 ** to enter a mutex.  If another thread is already within the mutex,
 242 ** sqlite3_mutex_enter() will block and sqlite3_mutex_try() will return
 243 ** SQLITE_BUSY.  The sqlite3_mutex_try() interface returns SQLITE_OK
 244 ** upon successful entry.  Mutexes created using SQLITE_MUTEX_RECURSIVE can
 245 ** be entered multiple times by the same thread.  In such cases the,
 246 ** mutex must be exited an equal number of times before another thread
 247 ** can enter.  If the same thread tries to enter any other kind of mutex
 248 ** more than once, the behavior is undefined.
 249 */
 250 static void winMutexEnter(sqlite3_mutex *p){
 251 #ifdef SQLITE_DEBUG
 252   DWORD tid = GetCurrentThreadId();
 253   assert( p->id==SQLITE_MUTEX_RECURSIVE || winMutexNotheld2(p, tid) );
 254 #endif
 255   EnterCriticalSection(&p->mutex);
 256 #ifdef SQLITE_DEBUG
 257   assert( p->nRef>0 || p->owner==0 );
 258   p->owner = tid;
 259   p->nRef++;
 260   if( p->trace ){
 261     printf("enter mutex %p (%d) with nRef=%d\n", p, p->trace, p->nRef);
 262   }
 263 #endif
 264 }
 265 static int winMutexTry(sqlite3_mutex *p){
 266 #ifndef NDEBUG
 267   DWORD tid = GetCurrentThreadId();
 268 #endif
 269   int rc = SQLITE_BUSY;
 270   assert( p->id==SQLITE_MUTEX_RECURSIVE || winMutexNotheld2(p, tid) );
 271   /*
 272   ** The sqlite3_mutex_try() routine is very rarely used, and when it
 273   ** is used it is merely an optimization.  So it is OK for it to always
 274   ** fail.
 275   **
 276   ** The TryEnterCriticalSection() interface is only available on WinNT.
 277   ** And some windows compilers complain if you try to use it without
 278   ** first doing some #defines that prevent SQLite from building on Win98.
 279   ** For that reason, we will omit this optimization for now.  See
 280   ** ticket #2685.
 281   */
 282 #if 0
 283   if( mutexIsNT() && TryEnterCriticalSection(&p->mutex) ){
 284     p->owner = tid;
 285     p->nRef++;
 286     rc = SQLITE_OK;
 287   }
 288 #else
 289   UNUSED_PARAMETER(p);
 290 #endif
 291 #ifdef SQLITE_DEBUG
 292   if( rc==SQLITE_OK && p->trace ){
 293     printf("try mutex %p (%d) with nRef=%d\n", p, p->trace, p->nRef);
 294   }
 295 #endif
 296   return rc;
 297 }
 298
 299 /*
 300 ** The sqlite3_mutex_leave() routine exits a mutex that was
 301 ** previously entered by the same thread.  The behavior
 302 ** is undefined if the mutex is not currently entered or
 303 ** is not currently allocated.  SQLite will never do either.
 304 */
 305 static void winMutexLeave(sqlite3_mutex *p){
 306 #ifndef NDEBUG
 307   DWORD tid = GetCurrentThreadId();
 308   assert( p->nRef>0 );
 309   assert( p->owner==tid );
 310   p->nRef--;
 311   if( p->nRef==0 ) p->owner = 0;
 312   assert( p->nRef==0 || p->id==SQLITE_MUTEX_RECURSIVE );
 313 #endif
 314   LeaveCriticalSection(&p->mutex);
 315 #ifdef SQLITE_DEBUG
 316   if( p->trace ){
 317     printf("leave mutex %p (%d) with nRef=%d\n", p, p->trace, p->nRef);
 318   }
 319 #endif
 320 }
 321
 322 sqlite3_mutex_methods const *sqlite3DefaultMutex(void){
 323   static const sqlite3_mutex_methods sMutex = {
 324     winMutexInit,
 325     winMutexEnd,
 326     winMutexAlloc,
 327     winMutexFree,
 328     winMutexEnter,
 329     winMutexTry,
 330     winMutexLeave,
 331 #ifdef SQLITE_DEBUG
 332     winMutexHeld,
 333     winMutexNotheld
 334 #else
 335     0,
 336     0
 337 #endif
 338   };
 339
 340   return &sMutex;
 341 }
 342 #endif /* SQLITE_MUTEX_W32 */