src/afs/lock.h

   1 /*
   2  * Copyright 2000, International Business Machines Corporation and others.
   3  * All Rights Reserved.
   4  *
   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
   8  */
   9
  10 #ifndef __AFSLOCK_INCLUDE__
  11 #define __AFSLOCK_INCLUDE__         1
  12
  13 #if !defined(lint) && !defined(LOCORE) && defined(RCS_HDRS)
  14 #endif
  15
  16 /*
  17  * (C) COPYRIGHT IBM CORPORATION 1987
  18  * LICENSED MATERIALS - PROPERTY OF IBM
  19  */
  20
  21 /* The following macros allow multi statement macros to be defined safely, i.e.
  22    - the multi statement macro can be the object of an if statement;
  23    - the call to the multi statement macro may be legally followed by a semi-colon.
  24    BEGINMAC and ENDMAC have been tested with both the portable C compiler and
  25    Hi-C.  Both compilers were from the Palo Alto 4.2BSD software releases, and
  26    both optimized out the constant loop code.  For an example of the use
  27    of BEGINMAC and ENDMAC, see the definition for ReleaseWriteLock, below.
  28    An alternative to this, using "if(1)" for BEGINMAC is not used because it
  29    may generate worse code with pcc, and may generate warning messages with hi-C.
  30 */
  31
  32 #if     (defined(AFS_SUN5_ENV)) || defined(AFS_OSF_ENV)
  33 #define AFS_NOBOZO_LOCK
  34 #endif
  35
  36 #if !defined(AFS_OSF20_ENV) || defined(AFS_OSF30_ENV) || defined(AFS_OSF32_ENV)
  37     /* We do not instrument locks on osf20 because the vcache structure
  38     ** exceeds the maximim possible limit for a vnode.
  39     */
  40 #define INSTRUMENT_LOCKS
  41 /* This is the max lock number in use. Please update it if you add any new
  42  * lock numbers.
  43  */
  44 #define MAX_LOCK_NUMBER 572
  45 #endif
  46
  47 struct afs_bozoLock {
  48     short count;    /* count of excl locks */
  49     char flags;     /* bit 1: is anyone waiting? */
  50     char spare;     /* for later */
  51     char *proc;     /* process holding the lock, really a struct proc * */
  52 };
  53 #ifndef AFS_NOBOZO_LOCK
  54 typedef struct afs_bozoLock afs_bozoLock_t;
  55 #else
  56 #ifdef  AFS_SUN5_ENV
  57 typedef kmutex_t afs_bozoLock_t;
  58 #else
  59 typedef struct afs_bozoLock afs_bozoLock_t;
  60 #endif
  61 #define afs_BozonLock(lock, avc)
  62 #define afs_BozonUnlock(lock, avc)
  63 #define afs_BozonInit(lock, nm)
  64 #define afs_CheckBozonLock(lock)                0
  65 #define afs_CheckBozonLockBlocking(lock)        0
  66 #endif
  67
  68 #define AFS_BOZONWAITING    1       /* someone is waiting for this lock */
  69
  70 #undef MObtainWriteLock         /* Defined also in ../rx/rx_machdep.h" */
  71 #undef MReleaseWriteLock
  72 #ifndef RXObtainWriteLock
  73 #define RXObtainWriteLock(lock) ObtainWriteLock(lock)
  74 #define RXReleaseWriteLock(lock) ReleaseWriteLock(lock)
  75 #endif
  76 #define MObtainReadLock(lock)   ObtainReadLock(lock)
  77 #define MObtainWriteLock(lock,src)      ObtainWriteLock(lock,src)
  78 #define MObtainSharedLock(lock,src)     ObtainSharedLock(lock,src)
  79 #define MUpgradeSToWLock(lock,src)      UpgradeSToWLock(lock,src)
  80 #define MConvertWToSLock(lock)  ConvertWToSLock(lock)
  81 #define MReleaseReadLock(lock)  ReleaseReadLock(lock)
  82 #define MReleaseWriteLock(lock) ReleaseWriteLock(lock)
  83 #define MReleaseSharedLock(lock) ReleaseSharedLock(lock)
  84
  85 #define RWLOCK_INIT(lock, nm)   Lock_Init(lock)
  86 #undef  LOCK_INIT
  87 #define LOCK_INIT(lock, nm)     Lock_Init(lock)
  88
  89 #define BEGINMAC do {
  90 #define ENDMAC   } while (0)
  91
  92 #if defined(AFS_SUN5_ENV)
  93 #define MyPidxx (curproc->p_pid)
  94 #else
  95 #if defined(AFS_AIX41_ENV)
  96 extern tid_t thread_self();
  97 #define MyPidxx thread_self()
  98 #else /* AFS_AIX41_ENV */
  99 #if defined(AFS_HPUX101_ENV)
 100 #define MyPidxx ((int)p_pid(u.u_procp))
 101 #else
 102 #if defined(AFS_SGI64_ENV)
 103 #if defined(AFS_SGI65_ENV)
 104 #define MyPidxx proc_pid(curproc())
 105 #else
 106 #define MyPidxx current_pid()
 107 #endif
 108 #else /* AFS_SGI64_ENV */
 109 #ifdef AFS_LINUX20_ENV
 110 #define MyPidxx current->pid
 111 #else
 112 #define MyPidxx (u.u_procp->p_pid )
 113 #endif /* AFS_LINUX20_ENV */
 114 #endif /* AFS_SGI64_ENV */
 115 #endif /* AFS_HPUX101_ENV */
 116 #endif /* AFS_AIX41_ENV */
 117 #endif
 118
 119 /* all locks wait on excl_locked except for READ_LOCK, which waits on readers_reading */
 120 struct afs_lock {
 121     unsigned char       wait_states;    /* type of lockers waiting */
 122     unsigned char       excl_locked;    /* anyone have boosted, shared or write lock? */
 123     unsigned short      readers_reading;/* # readers actually with read locks */
 124     unsigned short      num_waiting;    /* probably need this soon */
 125     unsigned short      spare;          /* not used now */
 126     osi_timeval_t       time_waiting;   /* for statistics gathering */
 127 #if defined(INSTRUMENT_LOCKS)
 128     /* the following are useful for debugging
 129     ** the field 'src_indicator' is updated only by ObtainLock() and
 130     ** only for writes/shared  locks. Hence, it indictes where in the
 131     ** source code the shared/write lock was set.
 132     */
 133     unsigned int        pid_last_reader;/* proceess id of last reader */
 134     unsigned int        pid_writer;     /* process id of writer, else 0 */
 135     unsigned int        src_indicator;  /* third param to ObtainLock()*/
 136 #endif /* INSTRUMENT_LOCKS */
 137 };
 138 typedef struct afs_lock afs_lock_t;
 139 typedef struct afs_lock afs_rwlock_t;
 140
 141 #define READ_LOCK       1
 142 #define WRITE_LOCK      2
 143 #define SHARED_LOCK     4
 144 /* this next is not a flag, but rather a parameter to Afs_Lock_Obtain */
 145 #define BOOSTED_LOCK 6
 146
 147 /* next defines wait_states for which we wait on excl_locked */
 148 #define EXCL_LOCKS (WRITE_LOCK|SHARED_LOCK)
 149
 150 #ifdef KERNEL
 151 #include "icl.h"
 152
 153 extern int afs_trclock;
 154 #if defined(INSTRUMENT_LOCKS)
 155
 156 #define ObtainReadLock(lock)\
 157   BEGINMAC  \
 158 /*       if (afs_trclock) {icl_Trace2(cm_iclSetp, CM_TRACE_LOCKOBTAIN, ICL_TYPE_POINTER, (long)lock, ICL_TYPE_LONG, (long)READ_LOCK);} */ \
 159         if (!((lock)->excl_locked & WRITE_LOCK)) \
 160             ((lock)->readers_reading)++; \
 161         else \
 162             Afs_Lock_Obtain(lock, READ_LOCK); \
 163         (lock)->pid_last_reader = MyPidxx; \
 164    ENDMAC
 165
 166 #define ObtainWriteLock(lock, src)\
 167   BEGINMAC  \
 168 /*       if (afs_trclock) {icl_Trace2(cm_iclSetp, CM_TRACE_LOCKOBTAIN, ICL_TYPE_POINTER, (long)lock, ICL_TYPE_LONG, (long)WRITE_LOCK);} */ \
 169         if (!(lock)->excl_locked && !(lock)->readers_reading)\
 170             (lock) -> excl_locked = WRITE_LOCK;\
 171         else\
 172             Afs_Lock_Obtain(lock, WRITE_LOCK); \
 173         (lock)->pid_writer = MyPidxx; \
 174         (lock)->src_indicator = src;\
 175    ENDMAC
 176
 177 #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)
 178
 179 #define ObtainSharedLock(lock, src)\
 180   BEGINMAC  \
 181 /*       if (afs_trclock) {icl_Trace2(cm_iclSetp, CM_TRACE_LOCKOBTAIN, ICL_TYPE_POINTER, (long)lock, ICL_TYPE_LONG, (long)SHARED_LOCK);} */ \
 182         if (!(lock)->excl_locked)\
 183             (lock) -> excl_locked = SHARED_LOCK;\
 184         else\
 185             Afs_Lock_Obtain(lock, SHARED_LOCK); \
 186         (lock)->pid_writer = MyPidxx; \
 187         (lock)->src_indicator = src;\
 188    ENDMAC
 189
 190 #define UpgradeSToWLock(lock, src)\
 191   BEGINMAC  \
 192 /*       if (afs_trclock) {icl_Trace2(cm_iclSetp, CM_TRACE_LOCKOBTAIN, ICL_TYPE_POINTER, (long)lock, ICL_TYPE_LONG, (long)BOOSTED_LOCK);} */ \
 193         if (!(lock)->readers_reading)\
 194             (lock)->excl_locked = WRITE_LOCK;\
 195         else\
 196             Afs_Lock_Obtain(lock, BOOSTED_LOCK); \
 197         (lock)->pid_writer = MyPidxx; \
 198         (lock)->src_indicator = src;\
 199    ENDMAC
 200
 201 /* this must only be called with a WRITE or boosted SHARED lock! */
 202 #define ConvertWToSLock(lock)\
 203         BEGINMAC\
 204 /*       if (afs_trclock) {icl_Trace2(cm_iclSetp, CM_TRACE_LOCKDOWN, ICL_TYPE_POINTER, (long)lock, ICL_TYPE_LONG, (long)SHARED_LOCK);} */ \
 205             (lock)->excl_locked = SHARED_LOCK; \
 206             if((lock)->wait_states) \
 207                 Afs_Lock_ReleaseR(lock); \
 208         ENDMAC
 209
 210 #define ConvertWToRLock(lock) \
 211         BEGINMAC\
 212 /*       if (afs_trclock) {icl_Trace2(cm_iclSetp, CM_TRACE_LOCKDOWN, ICL_TYPE_POINTER, (long)lock, ICL_TYPE_LONG, (long)READ_LOCK);} */ \
 213             (lock)->excl_locked &= ~(SHARED_LOCK | WRITE_LOCK);\
 214             ((lock)->readers_reading)++;\
 215             (lock)->pid_last_reader = MyPidxx ; \
 216             (lock)->pid_writer = 0;\
 217             Afs_Lock_ReleaseR(lock);\
 218         ENDMAC
 219
 220 #define ConvertSToRLock(lock) \
 221         BEGINMAC\
 222 /*       if (afs_trclock) {icl_Trace2(cm_iclSetp, CM_TRACE_LOCKDOWN, ICL_TYPE_POINTER, (long)lock, ICL_TYPE_LONG, (long)READ_LOCK);} */ \
 223             (lock)->excl_locked &= ~(SHARED_LOCK | WRITE_LOCK);\
 224             ((lock)->readers_reading)++;\
 225             (lock)->pid_last_reader = MyPidxx ; \
 226             (lock)->pid_writer = 0;\
 227             Afs_Lock_ReleaseR(lock);\
 228         ENDMAC
 229
 230 #define ReleaseReadLock(lock)\
 231         BEGINMAC\
 232 /*       if (afs_trclock) {icl_Trace2(cm_iclSetp, CM_TRACE_LOCKDONE, ICL_TYPE_POINTER, (long)lock, ICL_TYPE_LONG, (long)READ_LOCK);} */ \
 233             if (!(--((lock)->readers_reading)) && (lock)->wait_states)\
 234                 Afs_Lock_ReleaseW(lock) ; \
 235         if ( (lock)->pid_last_reader == MyPidxx ) \
 236                 (lock)->pid_last_reader =0;\
 237         ENDMAC
 238
 239 #define ReleaseWriteLock(lock)\
 240         BEGINMAC\
 241 /*       if (afs_trclock) {icl_Trace2(cm_iclSetp, CM_TRACE_LOCKDONE, ICL_TYPE_POINTER, (long)lock, ICL_TYPE_LONG, (long)WRITE_LOCK);} */ \
 242             (lock)->excl_locked &= ~WRITE_LOCK;\
 243             if ((lock)->wait_states) Afs_Lock_ReleaseR(lock);\
 244             (lock)->pid_writer=0; \
 245         ENDMAC
 246
 247 /* can be used on shared or boosted (write) locks */
 248 #define ReleaseSharedLock(lock)\
 249         BEGINMAC\
 250 /*       if (afs_trclock) {icl_Trace2(cm_iclSetp, CM_TRACE_LOCKDONE, ICL_TYPE_POINTER, (long)lock, ICL_TYPE_LONG, (long)SHARED_LOCK);} */ \
 251             (lock)->excl_locked &= ~(SHARED_LOCK | WRITE_LOCK);\
 252             if ((lock)->wait_states) Afs_Lock_ReleaseR(lock);\
 253             (lock)->pid_writer=0; \
 254         ENDMAC
 255
 256 #else /* INSTRUMENT_LOCKS */
 257
 258 #define ObtainReadLock(lock)\
 259   BEGINMAC  \
 260 /*       if (afs_trclock) {icl_Trace2(cm_iclSetp, CM_TRACE_LOCKOBTAIN, ICL_TYPE_POINTER, (long)lock, ICL_TYPE_LONG, (long)READ_LOCK);} */ \
 261         if (!((lock)->excl_locked & WRITE_LOCK)) \
 262             ((lock)->readers_reading)++; \
 263         else \
 264             Afs_Lock_Obtain(lock, READ_LOCK); \
 265    ENDMAC
 266
 267 #define ObtainWriteLock(lock, src)\
 268   BEGINMAC  \
 269 /*       if (afs_trclock) {icl_Trace2(cm_iclSetp, CM_TRACE_LOCKOBTAIN, ICL_TYPE_POINTER, (long)lock, ICL_TYPE_LONG, (long)WRITE_LOCK);} */ \
 270         if (!(lock)->excl_locked && !(lock)->readers_reading)\
 271             (lock) -> excl_locked = WRITE_LOCK;\
 272         else\
 273             Afs_Lock_Obtain(lock, WRITE_LOCK); \
 274    ENDMAC
 275
 276 #define NBObtainWriteLock(lock, src) (((lock)->excl_locked || (lock)->readers_reading) ? EWOULDBLOCK : ((lock) -> excl_locked = WRITE_LOCK),  0)
 277
 278 #define ObtainSharedLock(lock, src)\
 279   BEGINMAC  \
 280 /*       if (afs_trclock) {icl_Trace2(cm_iclSetp, CM_TRACE_LOCKOBTAIN, ICL_TYPE_POINTER, (long)lock, ICL_TYPE_LONG, (long)SHARED_LOCK);} */ \
 281         if (!(lock)->excl_locked)\
 282             (lock) -> excl_locked = SHARED_LOCK;\
 283         else\
 284             Afs_Lock_Obtain(lock, SHARED_LOCK); \
 285    ENDMAC
 286
 287 #define UpgradeSToWLock(lock, src)\
 288   BEGINMAC  \
 289 /*       if (afs_trclock) {icl_Trace2(cm_iclSetp, CM_TRACE_LOCKOBTAIN, ICL_TYPE_POINTER, (long)lock, ICL_TYPE_LONG, (long)BOOSTED_LOCK);} */ \
 290         if (!(lock)->readers_reading)\
 291             (lock)->excl_locked = WRITE_LOCK;\
 292         else\
 293             Afs_Lock_Obtain(lock, BOOSTED_LOCK); \
 294    ENDMAC
 295
 296 /* this must only be called with a WRITE or boosted SHARED lock! */
 297 #define ConvertWToSLock(lock)\
 298         BEGINMAC\
 299 /*       if (afs_trclock) {icl_Trace2(cm_iclSetp, CM_TRACE_LOCKDOWN, ICL_TYPE_POINTER, (long)lock, ICL_TYPE_LONG, (long)SHARED_LOCK);} */ \
 300             (lock)->excl_locked = SHARED_LOCK; \
 301             if((lock)->wait_states) \
 302                 Afs_Lock_ReleaseR(lock); \
 303         ENDMAC
 304
 305 #define ConvertWToRLock(lock) \
 306         BEGINMAC\
 307 /*       if (afs_trclock) {icl_Trace2(cm_iclSetp, CM_TRACE_LOCKDOWN, ICL_TYPE_POINTER, (long)lock, ICL_TYPE_LONG, (long)READ_LOCK);} */ \
 308             (lock)->excl_locked &= ~(SHARED_LOCK | WRITE_LOCK);\
 309             ((lock)->readers_reading)++;\
 310             Afs_Lock_ReleaseR(lock);\
 311         ENDMAC
 312
 313 #define ConvertSToRLock(lock) \
 314         BEGINMAC\
 315 /*       if (afs_trclock) {icl_Trace2(cm_iclSetp, CM_TRACE_LOCKDOWN, ICL_TYPE_POINTER, (long)lock, ICL_TYPE_LONG, (long)READ_LOCK);} */ \
 316             (lock)->excl_locked &= ~(SHARED_LOCK | WRITE_LOCK);\
 317             ((lock)->readers_reading)++;\
 318             Afs_Lock_ReleaseR(lock);\
 319         ENDMAC
 320
 321 #define ReleaseReadLock(lock)\
 322         BEGINMAC\
 323 /*       if (afs_trclock) {icl_Trace2(cm_iclSetp, CM_TRACE_LOCKDONE, ICL_TYPE_POINTER, (long)lock, ICL_TYPE_LONG, (long)READ_LOCK);} */ \
 324             if (!(--((lock)->readers_reading)) && (lock)->wait_states)\
 325                 Afs_Lock_ReleaseW(lock) ; \
 326         ENDMAC
 327
 328 #define ReleaseWriteLock(lock)\
 329         BEGINMAC\
 330 /*       if (afs_trclock) {icl_Trace2(cm_iclSetp, CM_TRACE_LOCKDONE, ICL_TYPE_POINTER, (long)lock, ICL_TYPE_LONG, (long)WRITE_LOCK);} */ \
 331             (lock)->excl_locked &= ~WRITE_LOCK;\
 332             if ((lock)->wait_states) Afs_Lock_ReleaseR(lock);\
 333         ENDMAC
 334
 335 /* can be used on shared or boosted (write) locks */
 336 #define ReleaseSharedLock(lock)\
 337         BEGINMAC\
 338 /*       if (afs_trclock) {icl_Trace2(cm_iclSetp, CM_TRACE_LOCKDONE, ICL_TYPE_POINTER, (long)lock, ICL_TYPE_LONG, (long)SHARED_LOCK);} */ \
 339             (lock)->excl_locked &= ~(SHARED_LOCK | WRITE_LOCK);\
 340             if ((lock)->wait_states) Afs_Lock_ReleaseR(lock);\
 341         ENDMAC
 342
 343 #endif /* INSTRUMENT_LOCKS */
 344
 345 /* I added this next macro to make sure it is safe to nuke a lock -- Mike K. */
 346 #define LockWaiters(lock)\
 347         ((int) ((lock)->num_waiting))
 348
 349 #define CheckLock(lock)\
 350         ((lock)->excl_locked? (int) -1 : (int) (lock)->readers_reading)
 351
 352 #define WriteLocked(lock)\
 353         ((lock)->excl_locked & WRITE_LOCK)
 354 #endif
 355
 356 /*
 357
 358 You can also use the lock package for handling parent locks for independently-lockable sets of
 359 small objects.  The concept here is that the parent lock is at the same level in the
 360 locking hierarchy as the little locks, but certain restrictions apply.
 361
 362 The general usage pattern is as follows.  You have a set of entries to search.  When searching it, you
 363 have a "scan" lock on the table.  If you find what you're looking for, you drop the lock down
 364 to a "hold" lock, lock the entry, and release the parent lock.  If you don't find what
 365 you're looking for, you create the entry, downgrade the "scan" lock to a "hold" lock,
 366 lock the entry and unlock the parent.
 367
 368 To delete an item from the table, you initially obtain a "purge" lock on the parent.  Unlike all
 369 of the other parent lock modes described herein, in order to obtain a "purge" lock mode, you
 370 must have released all locks on any items in the table.  Once you have obtained the parent
 371 lock in "purge" mode, you should check to see if the entry is locked.  If its not locked, you
 372 are free to delete the entry, knowing that no one else can attempt to obtain a lock
 373 on the entry while you have the purge lock held on the parent.  Unfortunately, if it *is* locked,
 374 you can not lock it yourself and wait for the other dude to release it, since the entry's locker
 375 may need to lock another entry before unlocking the entry you want (which would result in
 376 deadlock).  Instead, then, you must release the parent lock, and try again "later" (see Lock_Wait
 377 for assistance in waiting until later). Unfortunately, this is the best locking paradigm I've yet
 378 come up with.
 379
 380 What are the advantages to this scheme?  First, the use of the parent lock ensures that
 381 two people don't try to add the same entry at the same time or delete an entry while someone
 382 else is adding it.  It also ensures that when one process is deleting an entry, no one else is
 383 preparing to lock the entry.  Furthermore, when obtaining a lock on a little entry, you
 384 are only holding a "hold" lock on the parent lock, so that others may come in and search
 385 the table during this time.  Thus it will not hold up the system if a little entry takes
 386 a great deal of time to free up.
 387
 388 Here's how to compute the compatibility matrix:
 389
 390 The invariants are:
 391
 392 add     no deletions, additions allowed, additions will be performed, will obtain little locks
 393 hold    no deletions, additions allowed, no additions will be performed, will obtain little locks
 394 purge   no deletions or additions allowed, deletions will be performed, don't obtain little locks
 395
 396 When we compute the locking matrix, we note that hold is compatible with hold and add.
 397 Add is compatible only with hold.  purge is not compatible with anything.  This is the same
 398 matrix as obtained by mapping add->S, hold->read and purge->write locks.  Thus we
 399 can use the locks above to solve this problem, and we do.
 400
 401 */
 402
 403 #endif /* __AFSLOCK_INCLUDE__ */