2 * Copyright 2000, International Business Machines Corporation and others.
5 * This software has been released under the terms of the IBM Public
6 * License. For details, see the LICENSE file in the top-level source
7 * directory or online at http://www.openafs.org/dl/license10.html
10 #ifndef __AFSLOCK_INCLUDE__
11 #define __AFSLOCK_INCLUDE__ 1
13 #if !defined(KERNEL) && !defined(KDUMP_KERNEL)
14 #error Do not include afs/lock.h except for kernel code.
18 * (C) COPYRIGHT IBM CORPORATION 1987
19 * LICENSED MATERIALS - PROPERTY OF IBM
22 #define INSTRUMENT_LOCKS
23 /* This is the max lock number in use. Please update it if you add any new
26 #define MAX_LOCK_NUMBER 780
28 #define AFS_RWLOCK_INIT(lock, nm) Lock_Init(lock)
30 #define LOCK_INIT(lock, nm) Lock_Init(lock)
32 /* The following macros allow multi statement macros to be defined safely, i.e.
33 - the multi statement macro can be the object of an if statement;
34 - the call to the multi statement macro may be legally followed by a semi-colon.
35 BEGINMAC and ENDMAC have been tested with both the portable C compiler and
36 Hi-C. Both compilers were from the Palo Alto 4.2BSD software releases, and
37 both optimized out the constant loop code. For an example of the use
38 of BEGINMAC and ENDMAC, see the definition for ReleaseWriteLock, below.
39 An alternative to this, using "if(1)" for BEGINMAC is not used because it
40 may generate worse code with pcc, and may generate warning messages with hi-C.
44 #define ENDMAC } while (0)
47 typedef unsigned int afs_lock_tracker_t;
48 # define MyPidxx (get_user_struct()->u_procp->p_pid )
49 # define MyPidxx2Pid(x) (x)
50 #elif defined(AFS_SUN5_ENV)
51 typedef kthread_t * afs_lock_tracker_t;
52 # define MyPidxx (curthread)
53 # define MyPidxx2Pid(x) (x ? ttoproc(x)->p_pid : 0)
54 #elif defined(AFS_SUN5_ENV) || defined(AFS_OBSD_ENV)
55 typedef unsigned int afs_lock_tracker_t;
56 # define MyPidxx (curproc->p_pid)
57 # define MyPidxx2Pid(x) (x)
58 #elif defined(AFS_AIX41_ENV)
59 typedef tid_t afs_lock_tracker_t;
60 extern tid_t thread_self();
61 # define MyPidxx (thread_self())
62 # define MyPidxx2Pid(x) ((afs_int32)(x))
63 #elif defined(AFS_HPUX101_ENV)
64 # if defined(AFS_HPUX1111_ENV)
65 typedef struct kthread * afs_lock_tracker_t;
66 # define MyPidxx (u.u_kthreadp)
67 # define MyPidxx2Pid(x) (x ? kt_tid(x) : 0)
69 typedef afs_proc_t * afs_lock_tracker_t;
70 # define MyPidxx (u.u_procp)
71 # define MyPidxx2Pid(x) (x ? (afs_int32)p_pid(x) : 0)
73 #elif defined(AFS_SGI64_ENV)
74 # if defined(AFS_SGI65_ENV)
75 typedef unsigned int afs_lock_tracker_t;
76 # define MyPidxx proc_pid(curproc())
77 # define MyPidxx2Pid(x) (x)
79 typedef unsigned int afs_lock_tracker_t;
80 # define MyPidxx current_pid()
81 # define MyPidxx2Pid(x) (x)
83 #elif defined(AFS_LINUX20_ENV)
84 typedef struct task_struct * afs_lock_tracker_t;
85 # define MyPidxx (current)
86 # define MyPidxx2Pid(x) (x? (x)->pid : 0)
87 # define MyPid_NULL (NULL)
88 #elif defined(AFS_DARWIN_ENV)
89 # if defined(AFS_DARWIN80_ENV)
90 typedef unsigned int afs_lock_tracker_t;
91 # define MyPidxx (proc_selfpid())
92 # define MyPidxx2Pid(x) (x)
94 typedef unsigned int afs_lock_tracker_t;
95 # define MyPidxx (current_proc()->p_pid )
96 # define MyPidxx2Pid(x) (x)
98 #elif defined(AFS_FBSD_ENV)
99 typedef unsigned int afs_lock_tracker_t;
100 # define MyPidxx (curproc->p_pid )
101 # define MyPidxx2Pid(x) (x)
102 #elif defined(AFS_NBSD40_ENV)
103 typedef unsigned int afs_lock_tracker_t;
104 #define MyPidxx osi_getpid() /* XXX could generalize this (above) */
105 #define MyPidxx2Pid(x) (x)
107 typedef unsigned int afs_lock_tracker_t;
108 # define MyPidxx (u.u_procp->p_pid )
109 # define MyPidxx2Pid(x) (x)
113 # define MyPid_NULL (0)
116 /* all locks wait on excl_locked except for READ_LOCK, which waits on readers_reading */
118 unsigned char wait_states; /* type of lockers waiting */
119 unsigned char excl_locked; /* anyone have boosted, shared or write lock? */
120 unsigned short readers_reading; /* # readers actually with read locks */
121 unsigned short num_waiting; /* probably need this soon */
122 unsigned short spare; /* not used now */
123 osi_timeval_t time_waiting; /* for statistics gathering */
124 #if defined(INSTRUMENT_LOCKS)
125 /* the following are useful for debugging
126 ** the field 'src_indicator' is updated only by ObtainLock() and
127 ** only for writes/shared locks. Hence, it indictes where in the
128 ** source code the shared/write lock was set.
130 afs_lock_tracker_t pid_last_reader; /* proceess id of last reader */
131 afs_lock_tracker_t pid_writer; /* process id of writer, else 0 */
132 unsigned int src_indicator; /* third param to ObtainLock() */
133 #endif /* INSTRUMENT_LOCKS */
135 typedef struct afs_lock afs_lock_t;
136 typedef struct afs_lock afs_rwlock_t;
140 #define SHARED_LOCK 4
141 /* this next is not a flag, but rather a parameter to Afs_Lock_Obtain */
142 #define BOOSTED_LOCK 6
144 /* next defines wait_states for which we wait on excl_locked */
145 #define EXCL_LOCKS (WRITE_LOCK|SHARED_LOCK)
150 extern int afs_trclock;
152 #define AFS_LOCK_TRACE_ENABLE 0
153 #if AFS_LOCK_TRACE_ENABLE
154 #define AFS_LOCK_TRACE(op, lock, type) \
155 if (afs_trclock) Afs_Lock_Trace(op, lock, type, __FILE__, __LINE__);
157 #define AFS_LOCK_TRACE(op, lock, type)
160 #if defined(INSTRUMENT_LOCKS)
162 #define ObtainReadLock(lock)\
164 AFS_LOCK_TRACE(CM_TRACE_LOCKOBTAIN, lock, READ_LOCK);\
165 if (!((lock)->excl_locked & WRITE_LOCK)) \
166 ((lock)->readers_reading)++; \
168 Afs_Lock_Obtain(lock, READ_LOCK); \
169 (lock)->pid_last_reader = MyPidxx; \
172 #define NBObtainReadLock(lock) \
173 (((lock)->excl_locked & WRITE_LOCK) ? EWOULDBLOCK : (((lock)->readers_reading++), ((lock)->pid_last_reader = MyPidxx), 0))
175 #define ObtainWriteLock(lock, src)\
177 AFS_LOCK_TRACE(CM_TRACE_LOCKOBTAIN, lock, WRITE_LOCK);\
178 if (!(lock)->excl_locked && !(lock)->readers_reading)\
179 (lock) -> excl_locked = WRITE_LOCK;\
181 Afs_Lock_Obtain(lock, WRITE_LOCK); \
182 (lock)->pid_writer = MyPidxx; \
183 (lock)->src_indicator = src;\
186 #define NBObtainWriteLock(lock, src) (((lock)->excl_locked || (lock)->readers_reading) ? EWOULDBLOCK : (((lock) -> excl_locked = WRITE_LOCK), ((lock)->pid_writer = MyPidxx), ((lock)->src_indicator = src), 0))
188 #define ObtainSharedLock(lock, src)\
190 AFS_LOCK_TRACE(CM_TRACE_LOCKOBTAIN, lock, SHARED_LOCK);\
191 if (!(lock)->excl_locked)\
192 (lock) -> excl_locked = SHARED_LOCK;\
194 Afs_Lock_Obtain(lock, SHARED_LOCK); \
195 (lock)->pid_writer = MyPidxx; \
196 (lock)->src_indicator = src;\
199 #define NBObtainSharedLock(lock, src) (((lock)->excl_locked) ? EWOULDBLOCK : (((lock) -> excl_locked = SHARED_LOCK), ((lock)->pid_writer = MyPidxx), ((lock)->src_indicator = src), 0))
201 #define UpgradeSToWLock(lock, src)\
203 AFS_LOCK_TRACE(CM_TRACE_LOCKOBTAIN, lock, BOOSTED_LOCK);\
204 if (!(lock)->readers_reading)\
205 (lock)->excl_locked = WRITE_LOCK;\
207 Afs_Lock_Obtain(lock, BOOSTED_LOCK); \
208 (lock)->pid_writer = MyPidxx; \
209 (lock)->src_indicator = src;\
212 /* this must only be called with a WRITE or boosted SHARED lock! */
213 #define ConvertWToSLock(lock)\
215 AFS_LOCK_TRACE(CM_TRACE_LOCKDOWN, lock, SHARED_LOCK);\
216 (lock)->excl_locked = SHARED_LOCK; \
217 if((lock)->wait_states) \
218 Afs_Lock_ReleaseR(lock); \
221 #define ConvertWToRLock(lock) \
223 AFS_LOCK_TRACE(CM_TRACE_LOCKDOWN, lock, READ_LOCK);\
224 (lock)->excl_locked &= ~(SHARED_LOCK | WRITE_LOCK);\
225 ((lock)->readers_reading)++;\
226 (lock)->pid_last_reader = MyPidxx ; \
227 (lock)->pid_writer = MyPid_NULL;\
228 Afs_Lock_ReleaseR(lock);\
231 #define ConvertSToRLock(lock) \
233 AFS_LOCK_TRACE(CM_TRACE_LOCKDOWN, lock, READ_LOCK);\
234 (lock)->excl_locked &= ~(SHARED_LOCK | WRITE_LOCK);\
235 ((lock)->readers_reading)++;\
236 (lock)->pid_last_reader = MyPidxx ; \
237 (lock)->pid_writer = MyPid_NULL;\
238 Afs_Lock_ReleaseR(lock);\
241 #define ReleaseReadLock(lock)\
243 AFS_LOCK_TRACE(CM_TRACE_LOCKDONE, lock, READ_LOCK);\
244 if (!(--((lock)->readers_reading)) && (lock)->wait_states)\
245 Afs_Lock_ReleaseW(lock) ; \
246 if ( (lock)->pid_last_reader == MyPidxx ) \
247 (lock)->pid_last_reader = MyPid_NULL;\
250 #define ReleaseWriteLock(lock)\
252 AFS_LOCK_TRACE(CM_TRACE_LOCKDONE, lock, WRITE_LOCK);\
253 (lock)->excl_locked &= ~WRITE_LOCK;\
254 if ((lock)->wait_states) Afs_Lock_ReleaseR(lock);\
255 (lock)->pid_writer = MyPid_NULL; \
258 /* can be used on shared or boosted (write) locks */
259 #define ReleaseSharedLock(lock)\
261 AFS_LOCK_TRACE(CM_TRACE_LOCKDONE, lock, SHARED_LOCK);\
262 (lock)->excl_locked &= ~(SHARED_LOCK | WRITE_LOCK);\
263 if ((lock)->wait_states) Afs_Lock_ReleaseR(lock);\
264 (lock)->pid_writer = MyPid_NULL; \
267 #else /* INSTRUMENT_LOCKS */
269 #define ObtainReadLock(lock)\
271 AFS_LOCK_TRACE(CM_TRACE_LOCKOBTAIN, lock, READ_LOCK);\
272 if (!((lock)->excl_locked & WRITE_LOCK)) \
273 ((lock)->readers_reading)++; \
275 Afs_Lock_Obtain(lock, READ_LOCK); \
278 #define NBObtainReadLock(lock) \
279 (((lock)->excl_locked & WRITE_LOCK) ? EWOULDBLOCK : (((lock)->readers_reading++), 0))
281 #define ObtainWriteLock(lock, src)\
283 AFS_LOCK_TRACE(CM_TRACE_LOCKOBTAIN, lock, WRITE_LOCK);\
284 if (!(lock)->excl_locked && !(lock)->readers_reading)\
285 (lock) -> excl_locked = WRITE_LOCK;\
287 Afs_Lock_Obtain(lock, WRITE_LOCK); \
290 #define NBObtainWriteLock(lock, src) (((lock)->excl_locked || (lock)->readers_reading) ? EWOULDBLOCK : (((lock) -> excl_locked = WRITE_LOCK), 0))
292 #define ObtainSharedLock(lock, src)\
294 AFS_LOCK_TRACE(CM_TRACE_LOCKOBTAIN, lock, SHARED_LOCK);\
295 if (!(lock)->excl_locked)\
296 (lock) -> excl_locked = SHARED_LOCK;\
298 Afs_Lock_Obtain(lock, SHARED_LOCK); \
301 #define NBObtainSharedLock(lock, src) (((lock)->excl_locked) ? EWOULDBLOCK : (((lock) -> excl_locked = SHARED_LOCK), 0))
303 #define UpgradeSToWLock(lock, src)\
305 AFS_LOCK_TRACE(CM_TRACE_LOCKOBTAIN, lock, BOOSTED_LOCK);\
306 if (!(lock)->readers_reading)\
307 (lock)->excl_locked = WRITE_LOCK;\
309 Afs_Lock_Obtain(lock, BOOSTED_LOCK); \
312 /* this must only be called with a WRITE or boosted SHARED lock! */
313 #define ConvertWToSLock(lock)\
315 AFS_LOCK_TRACE(CM_TRACE_LOCKDOWN, lock, SHARED_LOCK);\
316 (lock)->excl_locked = SHARED_LOCK; \
317 if((lock)->wait_states) \
318 Afs_Lock_ReleaseR(lock); \
321 #define ConvertWToRLock(lock) \
323 AFS_LOCK_TRACE(CM_TRACE_LOCKDOWN, lock, READ_LOCK);\
324 (lock)->excl_locked &= ~(SHARED_LOCK | WRITE_LOCK);\
325 ((lock)->readers_reading)++;\
326 Afs_Lock_ReleaseR(lock);\
329 #define ConvertSToRLock(lock) \
331 AFS_LOCK_TRACE(CM_TRACE_LOCKDOWN, lock, READ_LOCK);\
332 (lock)->excl_locked &= ~(SHARED_LOCK | WRITE_LOCK);\
333 ((lock)->readers_reading)++;\
334 Afs_Lock_ReleaseR(lock);\
337 #define ReleaseReadLock(lock)\
339 AFS_LOCK_TRACE(CM_TRACE_LOCKDONE, lock, READ_LOCK);\
340 if (!(--((lock)->readers_reading)) && (lock)->wait_states)\
341 Afs_Lock_ReleaseW(lock) ; \
344 #define ReleaseWriteLock(lock)\
346 AFS_LOCK_TRACE(CM_TRACE_LOCKDONE, lock, WRITE_LOCK);\
347 (lock)->excl_locked &= ~WRITE_LOCK;\
348 if ((lock)->wait_states) Afs_Lock_ReleaseR(lock);\
351 /* can be used on shared or boosted (write) locks */
352 #define ReleaseSharedLock(lock)\
354 AFS_LOCK_TRACE(CM_TRACE_LOCKDONE, lock, SHARED_LOCK);\
355 (lock)->excl_locked &= ~(SHARED_LOCK | WRITE_LOCK);\
356 if ((lock)->wait_states) Afs_Lock_ReleaseR(lock);\
359 #endif /* INSTRUMENT_LOCKS */
361 /* I added this next macro to make sure it is safe to nuke a lock -- Mike K. */
362 #define LockWaiters(lock)\
363 ((int) ((lock)->num_waiting))
365 #define CheckLock(lock)\
366 ((lock)->excl_locked? (int) -1 : (int) (lock)->readers_reading)
368 #define WriteLocked(lock)\
369 ((lock)->excl_locked & WRITE_LOCK)
374 You can also use the lock package for handling parent locks for independently-lockable sets of
375 small objects. The concept here is that the parent lock is at the same level in the
376 locking hierarchy as the little locks, but certain restrictions apply.
378 The general usage pattern is as follows. You have a set of entries to search. When searching it, you
379 have a "scan" lock on the table. If you find what you're looking for, you drop the lock down
380 to a "hold" lock, lock the entry, and release the parent lock. If you don't find what
381 you're looking for, you create the entry, downgrade the "scan" lock to a "hold" lock,
382 lock the entry and unlock the parent.
384 To delete an item from the table, you initially obtain a "purge" lock on the parent. Unlike all
385 of the other parent lock modes described herein, in order to obtain a "purge" lock mode, you
386 must have released all locks on any items in the table. Once you have obtained the parent
387 lock in "purge" mode, you should check to see if the entry is locked. If its not locked, you
388 are free to delete the entry, knowing that no one else can attempt to obtain a lock
389 on the entry while you have the purge lock held on the parent. Unfortunately, if it *is* locked,
390 you can not lock it yourself and wait for the other dude to release it, since the entry's locker
391 may need to lock another entry before unlocking the entry you want (which would result in
392 deadlock). Instead, then, you must release the parent lock, and try again "later" (see Lock_Wait
393 for assistance in waiting until later). Unfortunately, this is the best locking paradigm I've yet
396 What are the advantages to this scheme? First, the use of the parent lock ensures that
397 two people don't try to add the same entry at the same time or delete an entry while someone
398 else is adding it. It also ensures that when one process is deleting an entry, no one else is
399 preparing to lock the entry. Furthermore, when obtaining a lock on a little entry, you
400 are only holding a "hold" lock on the parent lock, so that others may come in and search
401 the table during this time. Thus it will not hold up the system if a little entry takes
402 a great deal of time to free up.
404 Here's how to compute the compatibility matrix:
408 add no deletions, additions allowed, additions will be performed, will obtain little locks
409 hold no deletions, additions allowed, no additions will be performed, will obtain little locks
410 purge no deletions or additions allowed, deletions will be performed, don't obtain little locks
412 When we compute the locking matrix, we note that hold is compatible with hold and add.
413 Add is compatible only with hold. purge is not compatible with anything. This is the same
414 matrix as obtained by mapping add->S, hold->read and purge->write locks. Thus we
415 can use the locks above to solve this problem, and we do.
419 #endif /* __AFSLOCK_INCLUDE__ */