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