src/afs/DOC/afs_rwlocks

   1 Copyright 2000, International Business Machines Corporation and others.
   2 All Rights Reserved.
   3
   4 This software has been released under the terms of the IBM Public
   5 License.  For details, see the LICENSE file in the top-level source
   6 directory or online at http://www.openafs.org/dl/license10.html
   7
   8 Locking order (in order of locking) --
   9
  10 1.  PVN lock in cache entry.  Locks out pvn operations on vnode from
  11 our own layer.
  12
  13 2.  VCache entries.  Multiple ones can be locked, in which case
  14 they're locked in order of vnode within the same volume.  afs_AccessOK
  15 is called before locking other entries.
  16
  17 3. afs_xvcache locked before afs_xdcache in afs_remove, afs_symlink, etc
  18 in the file afs_vnodeops.c
  19
  20 4. afs_xvcache.  Must be able to load new cache
  21 entries while holding locks on others.  Note this means you can't lock
  22 a cache entry while holding either of this lock, unless, as in afs_create,
  23 the cache entry is actually created while the afs_xvcache is held.
  24
  25 5.  afs_xvcb.  Volume callback lock.  Locked before afs_xserver in afs_RemoveVCB.
  26
  27 6. afs_xvolume -- allows low-level server etc stuff to happen while
  28 creating a volume?
  29
  30 7.  afs_xuser -- afs_xuser locked before afs_xserver and afs_xconn in
  31 PUnlog.
  32
  33 8. afs_xcell -- locked before server in afs_GetCell.
  34
  35 9.  afs_xserver -- afs_xserver locked before afs_xconn in
  36 afs_ResetUserConns.
  37
  38 10. afs_xsrvAddr -- afs_xserver locked before afs_xsrvAddr in
  39 afs_CheckServers.
  40
  41 11.  afs_xconn  -- see above
  42
  43 12. Individual volume locks.  Must be after afs_xvolume so we can
  44 iterate over all volumes without others being inserted/deleted.  Same
  45 hack doesn't work for cache entry locks since we need to be able to
  46 lock multiple cache entries (but not multiple volumes) simultaneously.
  47
  48 13. afs_xdnlc -- locked after afs_xvcache in afs_osidnlc.c.  Shouldn't
  49 interact with any of the other locks.
  50
  51 14. afs_xcbhash -- No code which holds xcbhash (all of it is in
  52 afs_cbqueue.c) attempts to get any other locks, so it should always be
  53 obtained last.  It is locked in afs_DequeueCallbacks which is called from
  54 afs_FlushVCache with afs_xvcache write-locked.
  55
  56 ***** RX_ENABLE_LOCKS
  57
  58 Many fine grained locks are used by Rx on the AIX4.1 platform.  These
  59 need to be explained.
  60
  61 It is likely they could be used preference to the afs_rxglobal_lock on
  62 AFS_GLOBAL_SUNLOCK platforms.
  63
  64 ***** GLOBAL LOCKS
  65
  66 98. afs_global_lock -- This lock provides a non-preemptive environment
  67 for the bulk of the AFS kernel code on platforms that require it.
  68 Presently this includes SunOS5 and SGI53 systems.  This lock is dropped
  69 and reaquired frequently, especially around calls back to the OS that
  70 may reenter AFS such as vn_rele.
  71
  72     Generally, this lock should not be used to explicitly avoid locking
  73 data structures that need synchronization.  However, much existing code
  74 is deficient in this regard (e.g. afs_getevent).
  75
  76 99. afs_rxglobal_lock -- This lock is obtained after the afs_global_lock
  77 at process level but is obtained independently during packet arrival
  78 "interrupts" and during fasttimo processing.
  79
  80 ***** OS LOCKS
  81
  82 100. The vnode lock on SunOS and SGI53 protects the its reference count.
  83
  84 101. NETPRI/USERPRI -- These are not really locks but provide mutual
  85 exclusion against packet and timer interrupts.