blob: 20a4e0ea741e7d80b894dbdc94d390aa4875f495 [file] [log] [blame]
drh437b9012007-08-28 16:34:42 +00001/*
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**
drhed05efb2007-11-28 00:51:34 +000014** $Id: mutex_unix.c,v 1.3 2007/11/28 00:51:35 drh Exp $
drh437b9012007-08-28 16:34:42 +000015*/
16#include "sqliteInt.h"
17
18/*
19** The code in this file is only used if we are compiling threadsafe
20** under unix with pthreads.
21**
22** Note that this implementation requires a version of pthreads that
23** supports recursive mutexes.
24*/
25#ifdef SQLITE_MUTEX_PTHREADS
26
27#include <pthread.h>
28
drhed05efb2007-11-28 00:51:34 +000029
drh437b9012007-08-28 16:34:42 +000030/*
31** Each recursive mutex is an instance of the following structure.
32*/
33struct sqlite3_mutex {
34 pthread_mutex_t mutex; /* Mutex controlling the lock */
35 int id; /* Mutex type */
36 int nRef; /* Number of entrances */
37 pthread_t owner; /* Thread that is within this mutex */
drhd0679ed2007-08-28 22:24:34 +000038#ifdef SQLITE_DEBUG
39 int trace; /* True to trace changes */
40#endif
drh437b9012007-08-28 16:34:42 +000041};
42
43/*
44** The sqlite3_mutex_alloc() routine allocates a new
45** mutex and returns a pointer to it. If it returns NULL
46** that means that a mutex could not be allocated. SQLite
47** will unwind its stack and return an error. The argument
48** to sqlite3_mutex_alloc() is one of these integer constants:
49**
50** <ul>
51** <li> SQLITE_MUTEX_FAST
52** <li> SQLITE_MUTEX_RECURSIVE
53** <li> SQLITE_MUTEX_STATIC_MASTER
54** <li> SQLITE_MUTEX_STATIC_MEM
55** <li> SQLITE_MUTEX_STATIC_MEM2
56** <li> SQLITE_MUTEX_STATIC_PRNG
57** <li> SQLITE_MUTEX_STATIC_LRU
58** </ul>
59**
60** The first two constants cause sqlite3_mutex_alloc() to create
61** a new mutex. The new mutex is recursive when SQLITE_MUTEX_RECURSIVE
62** is used but not necessarily so when SQLITE_MUTEX_FAST is used.
63** The mutex implementation does not need to make a distinction
64** between SQLITE_MUTEX_RECURSIVE and SQLITE_MUTEX_FAST if it does
65** not want to. But SQLite will only request a recursive mutex in
66** cases where it really needs one. If a faster non-recursive mutex
67** implementation is available on the host platform, the mutex subsystem
68** might return such a mutex in response to SQLITE_MUTEX_FAST.
69**
70** The other allowed parameters to sqlite3_mutex_alloc() each return
71** a pointer to a static preexisting mutex. Three static mutexes are
72** used by the current version of SQLite. Future versions of SQLite
73** may add additional static mutexes. Static mutexes are for internal
74** use by SQLite only. Applications that use SQLite mutexes should
75** use only the dynamic mutexes returned by SQLITE_MUTEX_FAST or
76** SQLITE_MUTEX_RECURSIVE.
77**
78** Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST
79** or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc()
80** returns a different mutex on every call. But for the static
81** mutex types, the same mutex is returned on every call that has
82** the same type number.
83*/
84sqlite3_mutex *sqlite3_mutex_alloc(int iType){
85 static sqlite3_mutex staticMutexes[] = {
86 { PTHREAD_MUTEX_INITIALIZER, },
87 { PTHREAD_MUTEX_INITIALIZER, },
88 { PTHREAD_MUTEX_INITIALIZER, },
89 { PTHREAD_MUTEX_INITIALIZER, },
90 { PTHREAD_MUTEX_INITIALIZER, },
91 };
92 sqlite3_mutex *p;
93 switch( iType ){
94 case SQLITE_MUTEX_RECURSIVE: {
95 p = sqlite3MallocZero( sizeof(*p) );
96 if( p ){
drhed05efb2007-11-28 00:51:34 +000097#ifdef PTHREAD_MUTEX_RECURSIVE
98 /* Use a recursive mutex if it is available */
drh437b9012007-08-28 16:34:42 +000099 pthread_mutexattr_t recursiveAttr;
100 pthread_mutexattr_init(&recursiveAttr);
101 pthread_mutexattr_settype(&recursiveAttr, PTHREAD_MUTEX_RECURSIVE);
102 pthread_mutex_init(&p->mutex, &recursiveAttr);
103 pthread_mutexattr_destroy(&recursiveAttr);
drhed05efb2007-11-28 00:51:34 +0000104#else
105 /* If recursive mutexes are not available, we will have to
106 ** build our own. See below. */
107 pthread_mutex_init(&p->mutex, 0);
108#endif
drh437b9012007-08-28 16:34:42 +0000109 p->id = iType;
110 }
111 break;
112 }
113 case SQLITE_MUTEX_FAST: {
114 p = sqlite3MallocZero( sizeof(*p) );
115 if( p ){
116 p->id = iType;
117 pthread_mutex_init(&p->mutex, 0);
118 }
119 break;
120 }
121 default: {
122 assert( iType-2 >= 0 );
123 assert( iType-2 < sizeof(staticMutexes)/sizeof(staticMutexes[0]) );
124 p = &staticMutexes[iType-2];
125 p->id = iType;
126 break;
127 }
128 }
129 return p;
130}
131
132
133/*
134** This routine deallocates a previously
135** allocated mutex. SQLite is careful to deallocate every
136** mutex that it allocates.
137*/
138void sqlite3_mutex_free(sqlite3_mutex *p){
139 assert( p );
140 assert( p->nRef==0 );
141 assert( p->id==SQLITE_MUTEX_FAST || p->id==SQLITE_MUTEX_RECURSIVE );
142 pthread_mutex_destroy(&p->mutex);
143 sqlite3_free(p);
144}
145
146/*
147** The sqlite3_mutex_enter() and sqlite3_mutex_try() routines attempt
148** to enter a mutex. If another thread is already within the mutex,
149** sqlite3_mutex_enter() will block and sqlite3_mutex_try() will return
150** SQLITE_BUSY. The sqlite3_mutex_try() interface returns SQLITE_OK
151** upon successful entry. Mutexes created using SQLITE_MUTEX_RECURSIVE can
152** be entered multiple times by the same thread. In such cases the,
153** mutex must be exited an equal number of times before another thread
154** can enter. If the same thread tries to enter any other kind of mutex
155** more than once, the behavior is undefined.
156*/
157void sqlite3_mutex_enter(sqlite3_mutex *p){
158 assert( p );
159 assert( p->id==SQLITE_MUTEX_RECURSIVE || sqlite3_mutex_notheld(p) );
drhed05efb2007-11-28 00:51:34 +0000160
161#ifdef PTHREAD_MUTEX_RECURSIVE
162 /* Use the built-in recursive mutexes if they are available.
163 ** That they are not available on all systems.
164 */
drh437b9012007-08-28 16:34:42 +0000165 pthread_mutex_lock(&p->mutex);
166 p->owner = pthread_self();
167 p->nRef++;
drhed05efb2007-11-28 00:51:34 +0000168#else
169 /* If recursive mutexes are not available, then we have to grow
170 ** our own. This implementation assumes that pthread_equal()
171 ** is atomic - that it cannot be deceived into thinking self
172 ** and p->owner are equal if p->owner changes between two values
173 ** that are not equal to self while the comparison is taking place.
174 */
175 {
176 pthread_t self = pthread_self();
177 if( p->nRef>0 && pthread_equal(p->owner, self) ){
178 p->nRef++;
179 }else{
180 pthread_mutex_lock(&p->mutex);
181 assert( p->nRef==0 );
182 p->owner = self;
183 p->nRef = 1;
184 }
185 }
186#endif
187
drhd0679ed2007-08-28 22:24:34 +0000188#ifdef SQLITE_DEBUG
189 if( p->trace ){
190 printf("enter mutex %p (%d) with nRef=%d\n", p, p->trace, p->nRef);
191 }
192#endif
drh437b9012007-08-28 16:34:42 +0000193}
194int sqlite3_mutex_try(sqlite3_mutex *p){
195 int rc;
196 assert( p );
197 assert( p->id==SQLITE_MUTEX_RECURSIVE || sqlite3_mutex_notheld(p) );
drhed05efb2007-11-28 00:51:34 +0000198
199#ifdef PTHREAD_MUTEX_RECURSIVE
200 /* Use the built-in recursive mutexes if they are available.
201 ** That they are not available on all systems.
202 */
drh437b9012007-08-28 16:34:42 +0000203 if( pthread_mutex_trylock(&p->mutex)==0 ){
204 p->owner = pthread_self();
205 p->nRef++;
206 rc = SQLITE_OK;
207 }else{
208 rc = SQLITE_BUSY;
209 }
drhed05efb2007-11-28 00:51:34 +0000210#else
211 /* If recursive mutexes are not available, then we have to grow
212 ** our own. This implementation assumes that pthread_equal()
213 ** is atomic - that it cannot be deceived into thinking self
214 ** and p->owner are equal if p->owner changes between two values
215 ** that are not equal to self while the comparison is taking place.
216 */
217 {
218 pthread_t self = pthread_self();
219 if( p->nRef>0 && pthread_equal(p->owner, self) ){
220 p->nRef++;
221 rc = SQLITE_OK;
222 }else if( pthread_mutex_lock(&p->mutex)==0 ){
223 assert( p->nRef==0 );
224 p->owner = self;
225 p->nRef = 1;
226 rc = SQLITE_OK;
227 }else{
228 rc = SQLITE_BUSY;
229 }
230 }
231#endif
232
233#ifdef SQLITE_DEBUG
234 if( rc==SQLITE_OK && p->trace ){
235 printf("enter mutex %p (%d) with nRef=%d\n", p, p->trace, p->nRef);
236 }
237#endif
drh437b9012007-08-28 16:34:42 +0000238 return rc;
239}
240
241/*
242** The sqlite3_mutex_leave() routine exits a mutex that was
243** previously entered by the same thread. The behavior
244** is undefined if the mutex is not currently entered or
245** is not currently allocated. SQLite will never do either.
246*/
247void sqlite3_mutex_leave(sqlite3_mutex *p){
248 assert( p );
249 assert( sqlite3_mutex_held(p) );
250 p->nRef--;
251 assert( p->nRef==0 || p->id==SQLITE_MUTEX_RECURSIVE );
drhed05efb2007-11-28 00:51:34 +0000252
253#ifdef PTHREAD_RECURSIVE_MUTEX
254 pthread_mutex_unlock(&p->mutex);
255#else
256 if( p->nRef==0 ){
257 pthread_mutex_unlock(&p->mutex);
258 }
259#endif
260
drhd0679ed2007-08-28 22:24:34 +0000261#ifdef SQLITE_DEBUG
262 if( p->trace ){
263 printf("leave mutex %p (%d) with nRef=%d\n", p, p->trace, p->nRef);
264 }
265#endif
drh437b9012007-08-28 16:34:42 +0000266}
267
268/*
269** The sqlite3_mutex_held() and sqlite3_mutex_notheld() routine are
270** intended for use only inside assert() statements. On some platforms,
271** there might be race conditions that can cause these routines to
272** deliver incorrect results. In particular, if pthread_equal() is
273** not an atomic operation, then these routines might delivery
274** incorrect results. On most platforms, pthread_equal() is a
275** comparison of two integers and is therefore atomic. But we are
276** told that HPUX is not such a platform. If so, then these routines
277** will not always work correctly on HPUX.
278**
279** On those platforms where pthread_equal() is not atomic, SQLite
280** should be compiled without -DSQLITE_DEBUG and with -DNDEBUG to
281** make sure no assert() statements are evaluated and hence these
282** routines are never called.
283*/
284#ifndef NDEBUG
285int sqlite3_mutex_held(sqlite3_mutex *p){
286 return p==0 || (p->nRef!=0 && pthread_equal(p->owner, pthread_self()));
287}
288int sqlite3_mutex_notheld(sqlite3_mutex *p){
289 return p==0 || p->nRef==0 || pthread_equal(p->owner, pthread_self())==0;
290}
291#endif
292#endif /* SQLITE_MUTEX_PTHREAD */