Commit 86b5a738 authored by Paul E. McKenney's avatar Paul E. McKenney
Browse files

doc: Present the role of READ_ONCE() 



This commit adds an explanation of the special cases where READ_ONCE()
may be used in place of a member of the rcu_dereference() family.

Signed-off-by: default avatarPaul E. McKenney <paulmck@kernel.org>
parent 3650b228

Documentation/RCU/checklist.rst

+7 −0
Original line number Diff line number Diff line
@@ -314,6 +314,13 @@ over a rather long period of time, but improvements are always welcome! 
	shared between readers and updaters.  Additional primitives

	are provided for this case, as discussed in lockdep.txt.



	One exception to this rule is when data is only ever added to

	the linked data structure, and is never removed during any

	time that readers might be accessing that structure.  In such

	cases, READ_ONCE() may be used in place of rcu_dereference()

	and the read-side markers (rcu_read_lock() and rcu_read_unlock(),

	for example) may be omitted.



10.	Conversely, if you are in an RCU read-side critical section,

	and you don't hold the appropriate update-side lock, you -must-

	use the "_rcu()" variants of the list macros.  Failing to do so

Documentation/RCU/rcu_dereference.rst

+6 −0
Original line number Diff line number Diff line
@@ -28,6 +28,12 @@ Follow these rules to keep your RCU code working properly: 
	for an example where the compiler can in fact deduce the exact

	value of the pointer, and thus cause misordering.



-	In the special case where data is added but is never removed

	while readers are accessing the structure, READ_ONCE() may be used

	instead of rcu_dereference().  In this case, use of READ_ONCE()

	takes on the role of the lockless_dereference() primitive that

	was removed in v4.15.



-	You are only permitted to use rcu_dereference on pointer values.

	The compiler simply knows too much about integral values to

	trust it to carry dependencies through integer operations.