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)
pthreadMutexHeld(sqlite3_mutex * p)78 static int pthreadMutexHeld(sqlite3_mutex *p){
79 return (p->nRef!=0 && pthread_equal(p->owner, pthread_self()));
80 }
pthreadMutexNotheld(sqlite3_mutex * p)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 */
sqlite3MemoryBarrier(void)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 */
pthreadMutexInit(void)102 static int pthreadMutexInit(void){ return SQLITE_OK; }
pthreadMutexEnd(void)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_MAIN
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 */
pthreadMutexAlloc(int iType)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 */
pthreadMutexFree(sqlite3_mutex * p)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 */
pthreadMutexEnter(sqlite3_mutex * p)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 }
pthreadMutexTry(sqlite3_mutex * p)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 */
pthreadMutexLeave(sqlite3_mutex * p)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
sqlite3DefaultMutex(void)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 */
395