Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 6e676696 authored by Paul E. McKenney's avatar Paul E. McKenney
Browse files

documentation: Document call_rcu() safety mechanisms and limitations



The call_rcu() family of primitives will take action to accelerate
grace periods when the number of callbacks pending on a given CPU
becomes excessive.  Although this safety mechanism can be useful,
it is no substitute for users of call_rcu() having rate-limit controls
in place.  This commit adds this nuance to the documentation.

Reported-by: default avatar"Michael S. Tsirkin" <mst@redhat.com>
Reported-by: default avatarGleb Natapov <gleb@redhat.com>
Signed-off-by: default avatarPaul E. McKenney <paulmck@linux.vnet.ibm.com>
Reviewed-by: default avatarJosh Triplett <josh@joshtriplett.org>
parent 6d0abeca
Loading
Loading
Loading
Loading
+13 −5
Original line number Diff line number Diff line
@@ -256,10 +256,10 @@ over a rather long period of time, but improvements are always welcome!
		variations on this theme.

	b.	Limiting update rate.  For example, if updates occur only
		once per hour, then no explicit rate limiting is required,
		unless your system is already badly broken.  The dcache
		subsystem takes this approach -- updates are guarded
		by a global lock, limiting their rate.
		once per hour, then no explicit rate limiting is
		required, unless your system is already badly broken.
		Older versions of the dcache subsystem take this approach,
		guarding updates with a global lock, limiting their rate.

	c.	Trusted update -- if updates can only be done manually by
		superuser or some other trusted user, then it might not
@@ -268,7 +268,8 @@ over a rather long period of time, but improvements are always welcome!
		the machine.

	d.	Use call_rcu_bh() rather than call_rcu(), in order to take
		advantage of call_rcu_bh()'s faster grace periods.
		advantage of call_rcu_bh()'s faster grace periods.  (This
		is only a partial solution, though.)

	e.	Periodically invoke synchronize_rcu(), permitting a limited
		number of updates per grace period.
@@ -276,6 +277,13 @@ over a rather long period of time, but improvements are always welcome!
	The same cautions apply to call_rcu_bh(), call_rcu_sched(),
	call_srcu(), and kfree_rcu().

	Note that although these primitives do take action to avoid memory
	exhaustion when any given CPU has too many callbacks, a determined
	user could still exhaust memory.  This is especially the case
	if a system with a large number of CPUs has been configured to
	offload all of its RCU callbacks onto a single CPU, or if the
	system has relatively little free memory.

9.	All RCU list-traversal primitives, which include
	rcu_dereference(), list_for_each_entry_rcu(), and
	list_for_each_safe_rcu(), must be either within an RCU read-side