Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux

doc: Update rcu_access_pointer() advice in rcu_dereference.rst

This commit updates the rcu_access_pointer() advice, noting that its
return value should not be assigned to a local variable, and also noting
that there is little point in using rcu_access_pointer() within an RCU
read-side critical section.

Signed-off-by: Paul E. McKenney <paulmck@kernel.org>

+10 -4
+10 -4
Documentation/RCU/rcu_dereference.rst
··· 128 128 This sort of comparison occurs frequently when scanning 129 129 RCU-protected circular linked lists. 130 130 131 - Note that if checks for being within an RCU read-side 132 - critical section are not required and the pointer is never 133 - dereferenced, rcu_access_pointer() should be used in place 134 - of rcu_dereference(). 131 + Note that if the pointer comparison is done outside 132 + of an RCU read-side critical section, and the pointer 133 + is never dereferenced, rcu_access_pointer() should be 134 + used in place of rcu_dereference(). In most cases, 135 + it is best to avoid accidental dereferences by testing 136 + the rcu_access_pointer() return value directly, without 137 + assigning it to a variable. 138 + 139 + Within an RCU read-side critical section, there is little 140 + reason to use rcu_access_pointer(). 135 141 136 142 - The comparison is against a pointer that references memory 137 143 that was initialized "a long time ago." The reason