[hcoop/debian/openafs.git] / doc / txt / afs_rwlocks

Copyright 2000, International Business Machines Corporation and others.
All Rights Reserved.

This software has been released under the terms of the IBM Public
License.  For details, see the LICENSE file in the top-level source
directory or online at http://www.openafs.org/dl/license10.html

Locking order (in order of locking) --

0.1 afs_discon_lock. Locks the current disconnected state, so it
    can't be changed under active operations

1.  PVN lock in cache entry.  Locks out pvn operations on vnode from
our own layer.

2.  VCache entries.  Multiple ones can be locked, in which case
they're locked in order of vnode within the same volume.  afs_AccessOK
is called before locking other entries.

3.  VCache entry vlock (Solaris only).

4.  DCache entries.  Tentatively, multiple ones can be locked now.
Locking order between dcache entries is in increasing offset order.
However, if it turns out we never need to lock multiple dcache's,
we should just say it's not allowed, and simplify things.

5.  afs_xdcache.  Protects the dcache hash tables and afs_index* in
afs_dcache.c.  As with afs_xvcache below, a newly created dcache
entries can be locked while holding afs_xdcache.

Bugs: afs_xvcache locked before afs_xdcache in afs_remove, afs_symlink,
etc in the file afs_vnodeops.c

5.1.  unixusers. unixuser structs are locked before afs_xvcache in PSetTokens
via afs_NotifyUser and via afs_ResetUserConns. They are also locked before
afs_xvcache in afs_Analyze via afs_BlackListOnce.

6.  afs_xvcache.  Must be able to load new cache entries while holding
locks on others.  Note this means you can't lock a cache entry while
holding either of this lock, unless, as in afs_create, the cache entry
is actually created while the afs_xvcache is held.

6a. afs_disconDirtyLock. Protects the disconnected dirty and shadow
vcache queues. Must be after afs_xvcache, because we lock this whilst
hold xvcache in afs_create.

6b. afs_xvreclaim. Protects the lookaside reclaim list. Locked inside 
xvcache in FlushReclaimedVcaches via NewVCache or the 1 min loop.

7. afs_xvcb.  Volume callback lock.  Locked before afs_xserver in
afs_RemoveVCB.

8. afs_xvolume -- allows low-level server etc stuff to happen while
creating a volume?

9.  afs_xuser -- afs_xuser is locked before afs_xserver and afs_xconn
in PUnlog.

10. afs_xcell -- afs_xcell locked before afs_xserver in afs_GetCell.

11. afs_xserver -- locked before afs_xconn in afs_ResetUserConns.

12. afs_xsrvAddr -- afs_xserver locked before afs_xsrvAddr in
afs_CheckServers.

13. afs_xconn  -- see above

14. Individual volume locks.  Must be after afs_xvolume so we can
iterate over all volumes without others being inserted/deleted.  Same
hack doesn't work for cache entry locks since we need to be able to
lock multiple cache entries (but not multiple volumes) simultaneously.

In practice this appears to only be used to protect the status, name,
and root vnode and uniq. other users are not excluded, although
exclusion of multiple installs of a volume entry have been poorly done.

15. afs_xdnlc -- locked after afs_xvcache in afs_osidnlc.c.  Shouldn't 
interact with any of the other locks. 

16. afs_xcbhash -- No code which holds xcbhash (all of it is in
afs_cbqueue.c) (note: this doesn't seem to be true -- it's used
elsewhere too) attempts to get any other locks, so it should always
be obtained last.  It is locked in afs_DequeueCallbacks which is
called from afs_FlushVCache with afs_xvcache write-locked.

17. afs_dynrootDirLock -- afs_GetDynroot returns the lock held,
afs_PutDynroot releases it.

18. Dcache entry mflock -- used to atomize accesses and updates to
dcache mflags.

19. DCache entry tlock -- used to make atomic reads or writes to
the dcache refcount.

***** RX_ENABLE_LOCKS

Many fine grained locks are used by Rx on the AIX4.1 platform.  These
need to be explained.

***** GLOBAL LOCKS

98. afs_global_lock -- This lock provides a non-preemptive environment
for the bulk of the AFS kernel code on platforms that require it.
Presently this includes SunOS5 and SGI53 systems.  This lock is dropped
and reaquired frequently, especially around calls back to the OS that
may reenter AFS such as vn_rele.

    Generally, this lock should not be used to explicitly avoid locking
data structures that need synchronization.  However, much existing code
is deficient in this regard (e.g. afs_getevent).

***** OS LOCKS

100. The vnode lock on SunOS and SGI53 protects the its reference count.

101. NETPRI/USERPRI -- These are not really locks but provide mutual
exclusion against packet and timer interrupts.
Commit	Line	Data
805e021f CE	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	5.1. unixusers. unixuser structs are locked before afs_xvcache in PSetTokens
	35	via afs_NotifyUser and via afs_ResetUserConns. They are also locked before
	36	afs_xvcache in afs_Analyze via afs_BlackListOnce.
	37
	38	6. afs_xvcache. Must be able to load new cache entries while holding
	39	locks on others. Note this means you can't lock a cache entry while
	40	holding either of this lock, unless, as in afs_create, the cache entry
	41	is actually created while the afs_xvcache is held.
	42
	43	6a. afs_disconDirtyLock. Protects the disconnected dirty and shadow
	44	vcache queues. Must be after afs_xvcache, because we lock this whilst
	45	hold xvcache in afs_create.
	46
	47	6b. afs_xvreclaim. Protects the lookaside reclaim list. Locked inside
	48	xvcache in FlushReclaimedVcaches via NewVCache or the 1 min loop.
	49
	50	7. afs_xvcb. Volume callback lock. Locked before afs_xserver in
	51	afs_RemoveVCB.
	52
	53	8. afs_xvolume -- allows low-level server etc stuff to happen while
	54	creating a volume?
	55
	56	9. afs_xuser -- afs_xuser is locked before afs_xserver and afs_xconn
	57	in PUnlog.
	58
	59	10. afs_xcell -- afs_xcell locked before afs_xserver in afs_GetCell.
	60
	61	11. afs_xserver -- locked before afs_xconn in afs_ResetUserConns.
	62
	63	12. afs_xsrvAddr -- afs_xserver locked before afs_xsrvAddr in
	64	afs_CheckServers.
65
66	13. afs_xconn -- see above
67
68	14. Individual volume locks. Must be after afs_xvolume so we can
69	iterate over all volumes without others being inserted/deleted. Same
70	hack doesn't work for cache entry locks since we need to be able to
71	lock multiple cache entries (but not multiple volumes) simultaneously.
72
73	In practice this appears to only be used to protect the status, name,
74	and root vnode and uniq. other users are not excluded, although
75	exclusion of multiple installs of a volume entry have been poorly done.
76
77	15. afs_xdnlc -- locked after afs_xvcache in afs_osidnlc.c. Shouldn't
78	interact with any of the other locks.
79
80	16. afs_xcbhash -- No code which holds xcbhash (all of it is in
81	afs_cbqueue.c) (note: this doesn't seem to be true -- it's used
82	elsewhere too) attempts to get any other locks, so it should always
83	be obtained last. It is locked in afs_DequeueCallbacks which is
84	called from afs_FlushVCache with afs_xvcache write-locked.
85
86	17. afs_dynrootDirLock -- afs_GetDynroot returns the lock held,
87	afs_PutDynroot releases it.
88
89	18. Dcache entry mflock -- used to atomize accesses and updates to
90	dcache mflags.
91
92	19. DCache entry tlock -- used to make atomic reads or writes to
93	the dcache refcount.
94
95	***** RX_ENABLE_LOCKS
96
97	Many fine grained locks are used by Rx on the AIX4.1 platform. These
98	need to be explained.
99
100	***** GLOBAL LOCKS
101
102	98. afs_global_lock -- This lock provides a non-preemptive environment
103	for the bulk of the AFS kernel code on platforms that require it.
104	Presently this includes SunOS5 and SGI53 systems. This lock is dropped
105	and reaquired frequently, especially around calls back to the OS that
106	may reenter AFS such as vn_rele.
107
108	Generally, this lock should not be used to explicitly avoid locking
109	data structures that need synchronization. However, much existing code
110	is deficient in this regard (e.g. afs_getevent).
111
112	***** OS LOCKS
113
114	100. The vnode lock on SunOS and SGI53 protects the its reference count.
115
116	101. NETPRI/USERPRI -- These are not really locks but provide mutual
117	exclusion against packet and timer interrupts.