Documentation/RCU/checklist.rst

1 .. SPDX-License-Identifier: GPL-2.0
14 0.	Is RCU being applied to a read-mostly situation?  If the data
18 	tool for the job.  Yes, RCU does reduce read-side overhead by
19 	increasing write-side overhead, which is exactly why normal uses
27 	Yet another exception is where the low real-time latency of RCU's
28 	read-side primitives is critically important.
33 	counter-intuitive situation where rcu_read_lock() and
40 	RCU does allow -readers- to run (almost) naked, but -writers- must
49 	them -- even x86 allows later loads to be reordered to precede
59 2.	Do the RCU read-side critical sections make proper use of
63 	under your read-side code, which can greatly increase the
66 	As a rough rule of thumb, any dereference of an RCU-protected
68 	rcu_read_lock_sched(), or by the appropriate update-side lock.
72 	Letting RCU-protected pointers "leak" out of an RCU read-side
76 	-before- letting them out of the RCU read-side critical section.
87 		an RCU-protected list.	Alternatively, use the other
88 		RCU-protected data structures that have been added to
93 	b.	Proceed as in (a) above, but also maintain per-element
95 		that guard per-element state.  Of course, fields that
104 		Sequences of operations performed under a lock will -not-
124 	are weakly ordered -- even x86 CPUs allow later loads to be
126 	the following measures to prevent memory-corruption problems:
138 		code know exactly which pointers are protected by RCU.
149 		various "_rcu()" list-traversal primitives, such
151 		perfectly legal (if redundant) for update-side code to
152 		use rcu_dereference() and the "_rcu()" list-traversal
156 		of an RCU read-side critical section.  See lockdep.txt
160 		list-traversal primitives can substitute for a good
178 		in their respective types of RCU-protected lists.
181 		type of RCU-protected linked lists.
187 		be traversed by an RCU read-side critical section.
198 	as the non-expedited forms, but expediting is both expensive and
200 	to real-time workloads.  Use of the expedited primitives should
201 	be restricted to rare configuration-change operations that would
202 	not normally be undertaken while a real-time workload is running.
203 	However, real-time workloads can use rcupdate.rcu_normal kernel
210 	a single non-expedited primitive to cover the entire batch.
213 	of the system, especially to real-time workloads running on
217 	which is RCU-sched for PREEMPT=n and RCU-preempt for PREEMPT=y.
221 	or any pair of primitives that disables and re-enables preemption,
226 	the expedited primitives are the same as for their non-expedited
244 	synchronize_rcu() without synchronize_rcu()'s multi-millisecond
246 	forget" memory-freeing capabilities where it applies.
249 	primitive is that it automatically self-limits: if grace periods
256 	Ways of gaining this self-limiting property when using call_rcu()
259 	a.	Keeping a count of the number of data-structure elements
260 		used by the RCU-protected data structure, including
267 		One way to stall the updates is to acquire the update-side
268 		mutex.	(Don't try this with a spinlock -- other CPUs
283 	c.	Trusted update -- if updates can only be done manually by
301 9.	All RCU list-traversal primitives, which include
303 	list_for_each_safe_rcu(), must be either within an RCU read-side
304 	critical section or must be protected by appropriate update-side
305 	locks.	RCU read-side critical sections are delimited by
311 	The reason that it is permissible to use RCU list-traversal
312 	primitives when the update-side lock is held is that doing so
317 10.	Conversely, if you are in an RCU read-side critical section,
318 	and you don't hold the appropriate update-side lock, you -must-
333 	an issue, the memory-allocator locking handles it).  However,
342 	surviving CPU.	(If this was not the case, a self-spawning RCU
344 	Furthermore, CPUs designated by rcu_nocbs= might well -always-
346 	for some  real-time workloads, this is the whole point of using
349 13.	Unlike other forms of RCU, it -is- permissible to block in an
350 	SRCU read-side critical section (demarked by srcu_read_lock()
352 	Please note that if you don't need to sleep in read-side critical
364 	synchronize_srcu() waits only for SRCU read-side critical
367 	is what makes sleeping read-side critical sections tolerable --
370 	system than RCU would be if RCU's read-side critical sections
373 	The ability to sleep in read-side critical sections does not
376 	Second, grace-period-detection overhead is amortized only
380 	only in extremely read-intensive situations, or in situations
381 	requiring SRCU's read-side deadlock immunity or low read-side
387 	real-time workloads than is synchronize_rcu_expedited().
394 	is to wait until all pre-existing readers have finished before
395 	carrying out some otherwise-destructive operation.  It is
396 	therefore critically important to -first- remove any path
398 	destructive operation, and -only- -then- invoke call_rcu(),
401 	Because these primitives only wait for pre-existing readers, it
405 15.	The various RCU read-side primitives do -not- necessarily contain
408 	read-side critical sections.  It is the responsibility of the
409 	RCU update-side primitives to deal with this.
419 		check that accesses to RCU-protected data
421 		read-side critical section, while holding the right
432 		tag the pointer to the RCU-protected data
444 	it is absolutely -not- sufficient to wait for a grace period!
445 	The current (say) synchronize_rcu() implementation is -not-
452 	-	call_rcu() -> rcu_barrier()
453 	-	call_srcu() -> srcu_barrier()
455 	However, these barrier functions are absolutely -not- guaranteed
461 	all pre-existing call_rcu() callbacks, you will need to execute