iv/linux
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc: Make reader aware of rcu_dereference_protected

Browse Source 
The whatisRCU.txt document says rcu_dereference() cannot be used
outside of rcu_read_lock() protected sections.  The commit adds a
mention of rcu_dereference_protected(), so that the new reader knows
that this API can be used to avoid update-side use of rcu_read_lock()
and rcu_read_unlock().

Cc: tytso@mit.edu
Suggested-by: tytso@mit.edu
Signed-off-by: Joel Fernandes (Google) <joel@joelfernandes.org>
[ paulmck: Update wording, including further feedback from Joel. ]
Signed-off-by: Paul E. McKenney <paulmck@linux.ibm.com>
This commit is contained in:
Joel Fernandes (Google) 2018-10-08 18:33:41 -07:00 committed by Paul E. McKenney
parent 1c7d6d4411
commit 93eb14201f
1 changed files with 14 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
Documentation/RCU/whatisRCU.txt
View File

@ -266,7 +266,7 @@ rcu_dereference()
unnecessary overhead on Alpha CPUs. unnecessary overhead on Alpha CPUs.
Note that the value returned by rcu_dereference() is valid Note that the value returned by rcu_dereference() is valid
only within the enclosing RCU read-side critical section. only within the enclosing RCU read-side critical section [1].
For example, the following is -not- legal: For example, the following is -not- legal:
rcu_read_lock(); rcu_read_lock();
@ -292,6 +292,19 @@ rcu_dereference()
typically used indirectly, via the _rcu list-manipulation typically used indirectly, via the _rcu list-manipulation
primitives, such as list_for_each_entry_rcu(). primitives, such as list_for_each_entry_rcu().
[1] The variant rcu_dereference_protected() can be used outside
of an RCU read-side critical section as long as the usage is
protected by locks acquired by the update-side code. This variant
avoids the lockdep warning that would happen when using (for
example) rcu_dereference() without rcu_read_lock() protection.
Using rcu_dereference_protected() also has the advantage
of permitting compiler optimizations that rcu_dereference()
must prohibit. The rcu_dereference_protected() variant takes
a lockdep expression to indicate which locks must be acquired
by the caller. If the indicated protection is not provided,
a lockdep splat is emitted. See RCU/Design/Requirements.html
and the API's code comments for more details and example usage.
The following diagram shows how each API communicates among the The following diagram shows how each API communicates among the
reader, updater, and reclaimer. reader, updater, and reclaimer.