The following commit has been merged into the core/rcu branch of tip: Commit-ID: 86b5a7381b12b1d1d5558d8087e5bbd04b7cf702 Gitweb: https://git.kernel.org/tip/86b5a7381b12b1d1d5558d8087e5bbd04b7cf702 Author: Paul E. McKenney <paulmck@xxxxxxxxxx> AuthorDate: Thu, 24 Sep 2020 20:53:25 -07:00 Committer: Paul E. McKenney <paulmck@xxxxxxxxxx> CommitterDate: Mon, 02 Nov 2020 17:07:15 -08:00 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: Paul E. McKenney <paulmck@xxxxxxxxxx> --- Documentation/RCU/checklist.rst | 7 +++++++ Documentation/RCU/rcu_dereference.rst | 6 ++++++ 2 files changed, 13 insertions(+) diff --git a/Documentation/RCU/checklist.rst b/Documentation/RCU/checklist.rst index 2efed99..bb7128e 100644 --- a/Documentation/RCU/checklist.rst +++ b/Documentation/RCU/checklist.rst @@ -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 diff --git a/Documentation/RCU/rcu_dereference.rst b/Documentation/RCU/rcu_dereference.rst index c9667eb..f3e587a 100644 --- a/Documentation/RCU/rcu_dereference.rst +++ b/Documentation/RCU/rcu_dereference.rst @@ -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.
|