Skip to contentSkip to conversation

doc: Update the comparisons rule in rcu_dereference.txt

PATCH Applied Michalis Kokologiannakis 2 participants 2 messages Mar 20, 2017 – Mar 21, 2017

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

PATCH 1/1 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.

---
 Documentation/RCU/rcu_dereference.txt | 9 +++++++++
 1 file changed, 9 insertions(+)
Documentation/RCU/rcu_dereference.txt +9 -0
index c0bf244..b2a613f 100644
@@ -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
Signature · 1 line
2.1.4
#1 lore raw
Quoted 7 lines · Michalis Kokologiannakis

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.

Queued for review, thank you!

Thanx, Paul

Quoted 27 lines
---
 Documentation/RCU/rcu_dereference.txt | 9 +++++++++
 1 file changed, 9 insertions(+)
Documentation/RCU/rcu_dereference.txt +9 -0
index c0bf244..b2a613f 100644
@@ -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
Signature · 1 line
2.1.4