summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorMichalis Kokologiannakis <mixaskok@gmail.com>2017-03-20 22:38:35 +0100
committerPaul E. McKenney <paulmck@linux.vnet.ibm.com>2017-04-12 08:23:42 -0700
commit93728af0a1f63e13d6f7f56a434965b05b8b2abd (patch)
tree51e775a3be39b18e623c5726eece18b7bcc5a92c
parent066bb1c84aa430d15f36070471cbfe8976631cce (diff)
doc: Update the comparisons rule in rcu_dereference.txt
When an RCU-protected pointer is fetched but never dereferenced rcu_access_pointer() should be used in place of rcu_dereference(). This commit explicitly records this very fact in Documentation/ RCU/rcu_dereference.txt, in order to prevent the usage of rcu_dereference() in comparisons. Signed-off-by: Michalis Kokologiannakis <mixaskok@gmail.com> Signed-off-by: Paul E. McKenney <paulmck@linux.vnet.ibm.com>
-rw-r--r--Documentation/RCU/rcu_dereference.txt9
1 files changed, 9 insertions, 0 deletions
diff --git a/Documentation/RCU/rcu_dereference.txt b/Documentation/RCU/rcu_dereference.txt
index c0bf2441a2ba..b2a613f16d74 100644
--- a/Documentation/RCU/rcu_dereference.txt
+++ b/Documentation/RCU/rcu_dereference.txt
@@ -138,6 +138,15 @@ o Be very careful about comparing pointers obtained from
This sort of comparison occurs frequently when scanning
RCU-protected circular linked lists.
+ Note that if checks for being within an RCU read-side
+ critical section are not required and the pointer is never
+ dereferenced, rcu_access_pointer() should be used in place
+ of rcu_dereference(). The rcu_access_pointer() primitive
+ does not require an enclosing read-side critical section,
+ and also omits the smp_read_barrier_depends() included in
+ rcu_dereference(), which in turn should provide a small
+ performance gain in some CPUs (e.g., the DEC Alpha).
+
o The comparison is against a pointer that references memory
that was initialized "a long time ago." The reason
this is safe is that even if misordering occurs, the