aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/RCU/checklist.txt
diff options
context:
space:
mode:
authorPaul E. McKenney <paulmck@us.ibm.com>2005-09-10 03:26:24 -0400
committerLinus Torvalds <torvalds@g5.osdl.org>2005-09-10 13:06:24 -0400
commitdd81eca83c8300c95d8a1eaf0d38f56513711535 (patch)
treea1cb1aee24b703b86f7197cfe4f379529a683c5a /Documentation/RCU/checklist.txt
parent12c62c2e9abf8da804fe1def1f5bb44d023f569f (diff)
[PATCH] Yet another RCU documentation update
Update RCU documentation based on discussions and review of RCU-based tree patches. Add an introductory whatisRCU.txt file. Signed-off-by: <paulmck@us.ibm.com> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
Diffstat (limited to 'Documentation/RCU/checklist.txt')
-rw-r--r--Documentation/RCU/checklist.txt23
1 files changed, 12 insertions, 11 deletions
diff --git a/Documentation/RCU/checklist.txt b/Documentation/RCU/checklist.txt
index 8f3fb77c9cd..e118a7c1a09 100644
--- a/Documentation/RCU/checklist.txt
+++ b/Documentation/RCU/checklist.txt
@@ -43,6 +43,10 @@ over a rather long period of time, but improvements are always welcome!
43 rcu_read_lock_bh()) in the read-side critical sections, 43 rcu_read_lock_bh()) in the read-side critical sections,
44 and are also an excellent aid to readability. 44 and are also an excellent aid to readability.
45 45
46 As a rough rule of thumb, any dereference of an RCU-protected
47 pointer must be covered by rcu_read_lock() or rcu_read_lock_bh()
48 or by the appropriate update-side lock.
49
463. Does the update code tolerate concurrent accesses? 503. Does the update code tolerate concurrent accesses?
47 51
48 The whole point of RCU is to permit readers to run without 52 The whole point of RCU is to permit readers to run without
@@ -90,7 +94,11 @@ over a rather long period of time, but improvements are always welcome!
90 94
91 The rcu_dereference() primitive is used by the various 95 The rcu_dereference() primitive is used by the various
92 "_rcu()" list-traversal primitives, such as the 96 "_rcu()" list-traversal primitives, such as the
93 list_for_each_entry_rcu(). 97 list_for_each_entry_rcu(). Note that it is perfectly
98 legal (if redundant) for update-side code to use
99 rcu_dereference() and the "_rcu()" list-traversal
100 primitives. This is particularly useful in code
101 that is common to readers and updaters.
94 102
95 b. If the list macros are being used, the list_add_tail_rcu() 103 b. If the list macros are being used, the list_add_tail_rcu()
96 and list_add_rcu() primitives must be used in order 104 and list_add_rcu() primitives must be used in order
@@ -150,16 +158,9 @@ over a rather long period of time, but improvements are always welcome!
150 158
151 Use of the _rcu() list-traversal primitives outside of an 159 Use of the _rcu() list-traversal primitives outside of an
152 RCU read-side critical section causes no harm other than 160 RCU read-side critical section causes no harm other than
153 a slight performance degradation on Alpha CPUs and some 161 a slight performance degradation on Alpha CPUs. It can
154 confusion on the part of people trying to read the code. 162 also be quite helpful in reducing code bloat when common
155 163 code is shared between readers and updaters.
156 Another way of thinking of this is "If you are holding the
157 lock that prevents the data structure from changing, why do
158 you also need RCU-based protection?" That said, there may
159 well be situations where use of the _rcu() list-traversal
160 primitives while the update-side lock is held results in
161 simpler and more maintainable code. The jury is still out
162 on this question.
163 164
16410. Conversely, if you are in an RCU read-side critical section, 16510. Conversely, if you are in an RCU read-side critical section,
165 you -must- use the "_rcu()" variants of the list macros. 166 you -must- use the "_rcu()" variants of the list macros.