Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
doc: Add RCU guards to checklist.rst
Also note that RCU guards can be easier to use.
Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
+19
-8
+19
-8
Documentation/RCU/checklist.rst
+19
-8
Documentation/RCU/checklist.rst
···
69
69
Explicit disabling of preemption (preempt_disable(), for example)
70
70
can serve as rcu_read_lock_sched(), but is less readable and
71
71
prevents lockdep from detecting locking issues. Acquiring a
72
-
spinlock also enters an RCU read-side critical section.
72
+
raw spinlock also enters an RCU read-side critical section.
73
+
74
+
The guard(rcu)() and scoped_guard(rcu) primitives designate
75
+
the remainder of the current scope or the next statement,
76
+
respectively, as the RCU read-side critical section. Use of
77
+
these guards can be less error-prone than rcu_read_lock(),
78
+
rcu_read_unlock(), and friends.
73
79
74
80
Please note that you *cannot* rely on code known to be built
75
81
only in non-preemptible kernels. Such code can and will break,
···
411
405
13. Unlike most flavors of RCU, it *is* permissible to block in an
412
406
SRCU read-side critical section (demarked by srcu_read_lock()
413
407
and srcu_read_unlock()), hence the "SRCU": "sleepable RCU".
414
-
Please note that if you don't need to sleep in read-side critical
415
-
sections, you should be using RCU rather than SRCU, because RCU
416
-
is almost always faster and easier to use than is SRCU.
408
+
As with RCU, guard(srcu)() and scoped_guard(srcu) forms are
409
+
available, and often provide greater ease of use. Please note
410
+
that if you don't need to sleep in read-side critical sections,
411
+
you should be using RCU rather than SRCU, because RCU is almost
412
+
always faster and easier to use than is SRCU.
417
413
418
414
Also unlike other forms of RCU, explicit initialization and
419
415
cleanup is required either at build time via DEFINE_SRCU()
···
451
443
real-time workloads than is synchronize_rcu_expedited().
452
444
453
445
It is also permissible to sleep in RCU Tasks Trace read-side
454
-
critical section, which are delimited by rcu_read_lock_trace() and
455
-
rcu_read_unlock_trace(). However, this is a specialized flavor
456
-
of RCU, and you should not use it without first checking with
457
-
its current users. In most cases, you should instead use SRCU.
446
+
critical section, which are delimited by rcu_read_lock_trace()
447
+
and rcu_read_unlock_trace(). However, this is a specialized
448
+
flavor of RCU, and you should not use it without first checking
449
+
with its current users. In most cases, you should instead
450
+
use SRCU. As with RCU and SRCU, guard(rcu_tasks_trace)() and
451
+
scoped_guard(rcu_tasks_trace) are available, and often provide
452
+
greater ease of use.
458
453
459
454
Note that rcu_assign_pointer() relates to SRCU just as it does to
460
455
other forms of RCU, but instead of rcu_dereference() you should