Documentation/RCU/checklist.rst

9 that make use of RCU.  Violating any of the rules listed below will
10 result in the same sorts of problems that leaving out a locking primitive
17 	performance measurements show that RCU is nonetheless the right
36 	of lockless algorithms that garbage collectors do.
54 	relating to itself that other tasks can read, there by definition
55 	can be no bottleneck).	Note that the definition of "large" has
74 	Please note that you *cannot* rely on code known to be built
87 	any locks or atomic operations.  This means that readers will
94 		RCU-protected data structures that have been added to
100 		locks (that are acquired by both readers and writers)
101 		that guard per-element state.  Fields that the readers
119 	d.	Carefully order the updates and the reads so that readers
130 		changing data into a separate structure, so that the
140 		accesses.  The rcu_dereference() primitive ensures that
142 		that the pointer points to.  This really is necessary
148 		Please note that compilers can also reorder code, and
150 		just that.  The rcu_dereference() primitive therefore also
158 		as the list_for_each_entry_rcu().  Note that it is
161 		primitives.  This is particularly useful in code that
191 	e.	Updates must ensure that initialization of a given
192 		structure happens before pointers to that structure are
194 		when publicizing a pointer to a structure that can
201 	If you need the callback to block, run that code in a workqueue
214 	configuration-change operations that would not normally be
215 	undertaken while a real-time workload is running.  Note that
222 	Restructure your code so that it batches the updates, allowing
234 	rcu_read_unlock(), (2) any pair of primitives that disables
236 	rcu_read_unlock_bh(), or (3) any pair of primitives that disables
248 		executing voluntary context switches, that is, from
257 		then the corresponding readers must use anything that
270 	that this usage is safe is that readers can use anything that
285 	primitive is that it automatically self-limits: if grace periods
308 		the memory allocator, so that this wrapper function
322 		here is that superuser already has lots of ways to crash
332 	Note that although these primitives do take action to avoid
349 	The reason that it is permissible to use RCU list-traversal
350 	primitives when the update-side lock is held is that doing so
357 	time that readers might be accessing that structure.  In such
370 	disable softirq on a given acquisition of that lock will result
372 	your RCU callback while interrupting that acquisition's critical
376 	the callback code simply wrappers around kfree(), so that this
377 	is not an issue (or, more accurately, to the extent that it is
381 	to safely access and/or modify that data structure.
383 	Do not assume that RCU callbacks will be executed on the same
384 	CPU that executed the corresponding call_rcu(), call_srcu(),
387 	then that RCU callback will execute on some surviving CPU.
395 	In addition, do not assume that callbacks queued in a given order
396 	will be invoked in that order, even if they all are queued on the
397 	same CPU.  Furthermore, do not assume that same-CPU callbacks will
401 	might be concurrently invoked by that CPU's softirq handler and
402 	that CPU's rcuo kthread.  At such times, that CPU's callbacks
408 	Please note that if you don't need to sleep in read-side critical
416 	"struct srcu_struct" that defines the scope of a given
422 	calls that have been passed the same srcu_struct.  This property
451 	Note that rcu_assign_pointer() relates to SRCU just as it does to
459 	that readers can follow that could be affected by the
464 	is the caller's responsibility to guarantee that any subsequent
481 		check that accesses to RCU-protected data structures
487 		check that you don't pass the same object to call_rcu()
489 		since the last time that you passed that same object to
500 		with __rcu, and sparse will warn you if you access that
504 	These debugging aids can help you find problems that are
510 	pending callbacks to be invoked before unloading that module.
511 	Note that it is absolutely *not* sufficient to wait for a grace
514 	call_rcu().  Or even on the current CPU if that CPU recently