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>

diff --git a/Documentation/RCU/rcu_dereference.rst b/Documentation/RCU/rcu_dereference.rst
index 0b418a5..81e828c 100644 (file)
--- a/Documentation/RCU/rcu_dereference.rst
+++ b/Documentation/RCU/rcu_dereference.rst
@@ -128,10 +128,16 @@ Follow these rules to keep your RCU code working properly:
                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().
+               Note that if the pointer comparison is done outside
+               of an RCU read-side critical section, and the pointer
+               is never dereferenced, rcu_access_pointer() should be
+               used in place of rcu_dereference().  In most cases,
+               it is best to avoid accidental dereferences by testing
+               the rcu_access_pointer() return value directly, without
+               assigning it to a variable.
+
+               Within an RCU read-side critical section, there is little
+               reason to use rcu_access_pointer().
 
        -       The comparison is against a pointer that references memory
                that was initialized "a long time ago."  The reason