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 0.1 afs_discon_lock. Locks the current disconnected state, so it
  11     can't be changed under active operations
  12
  13 1.  PVN lock in cache entry.  Locks out pvn operations on vnode from
  14 our own layer.
  15
  16 2.  VCache entries.  Multiple ones can be locked, in which case
  17 they're locked in order of vnode within the same volume.  afs_AccessOK
  18 is called before locking other entries.
  19
  20 3.  VCache entry vlock (Solaris only).
  21
  22 4.  DCache entries.  Tentatively, multiple ones can be locked now.
  23 Locking order between dcache entries is in increasing offset order.
  24 However, if it turns out we never need to lock multiple dcache's,
  25 we should just say it's not allowed, and simplify things.
  26
  27 5.  afs_xdcache.  Protects the dcache hash tables and afs_index* in
  28 afs_dcache.c.  As with afs_xvcache below, a newly created dcache
  29 entries can be locked while holding afs_xdcache.
  30
  31 Bugs: afs_xvcache locked before afs_xdcache in afs_remove, afs_symlink,
  32 etc in the file afs_vnodeops.c
  33
  34 6.  afs_xvcache.  Must be able to load new cache entries while holding
  35 locks on others.  Note this means you can't lock a cache entry while
  36 holding either of this lock, unless, as in afs_create, the cache entry
  37 is actually created while the afs_xvcache is held.
  38
  39 6a. afs_disconDirtyLock. Protects the disconnected dirty and shadow
  40 vcache queues. Must be after afs_xvcache, because we lock this whilst
  41 hold xvcache in afs_create.
  42
  43 6b. afs_xvreclaim. Protects the lookaside reclaim list. Locked inside
  44 xvcache in FlushReclaimedVcaches via NewVCache or the 1 min loop.
  45
  46 7. afs_xvcb.  Volume callback lock.  Locked before afs_xserver in
  47 afs_RemoveVCB.
  48
  49 8. afs_xvolume -- allows low-level server etc stuff to happen while
  50 creating a volume?
  51
  52 9.  afs_xuser -- afs_xuser is locked before afs_xserver and afs_xconn
  53 in PUnlog.
  54
  55 10. afs_xcell -- afs_xcell locked before afs_xserver in afs_GetCell.
  56
  57 11. afs_xserver -- locked before afs_xconn in afs_ResetUserConns.
  58
  59 12. afs_xsrvAddr -- afs_xserver locked before afs_xsrvAddr in
  60 afs_CheckServers.
  61
  62 13. afs_xconn  -- see above
  63
  64 14. Individual volume locks.  Must be after afs_xvolume so we can
  65 iterate over all volumes without others being inserted/deleted.  Same
  66 hack doesn't work for cache entry locks since we need to be able to
  67 lock multiple cache entries (but not multiple volumes) simultaneously.
  68
  69 15. afs_xdnlc -- locked after afs_xvcache in afs_osidnlc.c.  Shouldn't
  70 interact with any of the other locks.
  71
  72 16. afs_xcbhash -- No code which holds xcbhash (all of it is in
  73 afs_cbqueue.c) (note: this doesn't seem to be true -- it's used
  74 elsewhere too) attempts to get any other locks, so it should always
  75 be obtained last.  It is locked in afs_DequeueCallbacks which is
  76 called from afs_FlushVCache with afs_xvcache write-locked.
  77
  78 17. afs_dynrootDirLock -- afs_GetDynroot returns the lock held,
  79 afs_PutDynroot releases it.
  80
  81 18. Dcache entry mflock -- used to atomize accesses and updates to
  82 dcache mflags.
  83
  84 19. DCache entry tlock -- used to make atomic reads or writes to
  85 the dcache refcount.
  86
  87 ***** RX_ENABLE_LOCKS
  88
  89 Many fine grained locks are used by Rx on the AIX4.1 platform.  These
  90 need to be explained.
  91
  92 ***** GLOBAL LOCKS
  93
  94 98. afs_global_lock -- This lock provides a non-preemptive environment
  95 for the bulk of the AFS kernel code on platforms that require it.
  96 Presently this includes SunOS5 and SGI53 systems.  This lock is dropped
  97 and reaquired frequently, especially around calls back to the OS that
  98 may reenter AFS such as vn_rele.
  99
 100     Generally, this lock should not be used to explicitly avoid locking
 101 data structures that need synchronization.  However, much existing code
 102 is deficient in this regard (e.g. afs_getevent).
 103
 104 ***** OS LOCKS
 105
 106 100. The vnode lock on SunOS and SGI53 protects the its reference count.
 107
 108 101. NETPRI/USERPRI -- These are not really locks but provide mutual
 109 exclusion against packet and timer interrupts.