Commit 236fefaf authored by Paul E. McKenney's avatar Paul E. McKenney

rcu: Call out dangers of expedited RCU primitives

The expedited RCU primitives can be quite useful, but they have some
high costs as well.  This commit updates and creates docbook comments
calling out the costs, and updates the RCU documentation as well.
Signed-off-by: default avatarPaul E. McKenney <paulmck@linux.vnet.ibm.com>
parent 2036d94a
...@@ -180,6 +180,20 @@ over a rather long period of time, but improvements are always welcome! ...@@ -180,6 +180,20 @@ over a rather long period of time, but improvements are always welcome!
operations that would not normally be undertaken while a real-time operations that would not normally be undertaken while a real-time
workload is running. workload is running.
In particular, if you find yourself invoking one of the expedited
primitives repeatedly in a loop, please do everyone a favor:
Restructure your code so that it batches the updates, allowing
a single non-expedited primitive to cover the entire batch.
This will very likely be faster than the loop containing the
expedited primitive, and will be much much easier on the rest
of the system, especially to real-time workloads running on
the rest of the system.
In addition, it is illegal to call the expedited forms from
a CPU-hotplug notifier, or while holding a lock that is acquired
by a CPU-hotplug notifier. Failing to observe this restriction
will result in deadlock.
7. If the updater uses call_rcu() or synchronize_rcu(), then the 7. If the updater uses call_rcu() or synchronize_rcu(), then the
corresponding readers must use rcu_read_lock() and corresponding readers must use rcu_read_lock() and
rcu_read_unlock(). If the updater uses call_rcu_bh() or rcu_read_unlock(). If the updater uses call_rcu_bh() or
......
...@@ -63,6 +63,22 @@ extern void synchronize_rcu_expedited(void); ...@@ -63,6 +63,22 @@ extern void synchronize_rcu_expedited(void);
void kfree_call_rcu(struct rcu_head *head, void (*func)(struct rcu_head *rcu)); void kfree_call_rcu(struct rcu_head *head, void (*func)(struct rcu_head *rcu));
/**
* synchronize_rcu_bh_expedited - Brute-force RCU-bh grace period
*
* Wait for an RCU-bh grace period to elapse, but use a "big hammer"
* approach to force the grace period to end quickly. This consumes
* significant time on all CPUs and is unfriendly to real-time workloads,
* so is thus not recommended for any sort of common-case code. In fact,
* if you are using synchronize_rcu_bh_expedited() in a loop, please
* restructure your code to batch your updates, and then use a single
* synchronize_rcu_bh() instead.
*
* Note that it is illegal to call this function while holding any lock
* that is acquired by a CPU-hotplug notifier. And yes, it is also illegal
* to call this function from a CPU-hotplug notifier. Failing to observe
* these restriction will result in deadlock.
*/
static inline void synchronize_rcu_bh_expedited(void) static inline void synchronize_rcu_bh_expedited(void)
{ {
synchronize_sched_expedited(); synchronize_sched_expedited();
......
...@@ -1961,15 +1961,21 @@ static int synchronize_sched_expedited_cpu_stop(void *data) ...@@ -1961,15 +1961,21 @@ static int synchronize_sched_expedited_cpu_stop(void *data)
return 0; return 0;
} }
/* /**
* Wait for an rcu-sched grace period to elapse, but use "big hammer" * synchronize_sched_expedited - Brute-force RCU-sched grace period
* approach to force grace period to end quickly. This consumes *
* significant time on all CPUs, and is thus not recommended for * Wait for an RCU-sched grace period to elapse, but use a "big hammer"
* any sort of common-case code. * approach to force the grace period to end quickly. This consumes
* significant time on all CPUs and is unfriendly to real-time workloads,
* so is thus not recommended for any sort of common-case code. In fact,
* if you are using synchronize_sched_expedited() in a loop, please
* restructure your code to batch your updates, and then use a single
* synchronize_sched() instead.
* *
* Note that it is illegal to call this function while holding any * Note that it is illegal to call this function while holding any lock
* lock that is acquired by a CPU-hotplug notifier. Failing to * that is acquired by a CPU-hotplug notifier. And yes, it is also illegal
* observe this restriction will result in deadlock. * to call this function from a CPU-hotplug notifier. Failing to observe
* these restriction will result in deadlock.
* *
* This implementation can be thought of as an application of ticket * This implementation can be thought of as an application of ticket
* locking to RCU, with sync_sched_expedited_started and * locking to RCU, with sync_sched_expedited_started and
......
...@@ -835,10 +835,22 @@ sync_rcu_preempt_exp_init(struct rcu_state *rsp, struct rcu_node *rnp) ...@@ -835,10 +835,22 @@ sync_rcu_preempt_exp_init(struct rcu_state *rsp, struct rcu_node *rnp)
rcu_report_exp_rnp(rsp, rnp, false); /* Don't wake self. */ rcu_report_exp_rnp(rsp, rnp, false); /* Don't wake self. */
} }
/* /**
* Wait for an rcu-preempt grace period, but expedite it. The basic idea * synchronize_rcu_expedited - Brute-force RCU grace period
* is to invoke synchronize_sched_expedited() to push all the tasks to *
* the ->blkd_tasks lists and wait for this list to drain. * Wait for an RCU-preempt grace period, but expedite it. The basic
* idea is to invoke synchronize_sched_expedited() to push all the tasks to
* the ->blkd_tasks lists and wait for this list to drain. This consumes
* significant time on all CPUs and is unfriendly to real-time workloads,
* so is thus not recommended for any sort of common-case code.
* In fact, if you are using synchronize_rcu_expedited() in a loop,
* please restructure your code to batch your updates, and then Use a
* single synchronize_rcu() instead.
*
* Note that it is illegal to call this function while holding any lock
* that is acquired by a CPU-hotplug notifier. And yes, it is also illegal
* to call this function from a CPU-hotplug notifier. Failing to observe
* these restriction will result in deadlock.
*/ */
void synchronize_rcu_expedited(void) void synchronize_rcu_expedited(void)
{ {
......
...@@ -286,19 +286,26 @@ void synchronize_srcu(struct srcu_struct *sp) ...@@ -286,19 +286,26 @@ void synchronize_srcu(struct srcu_struct *sp)
EXPORT_SYMBOL_GPL(synchronize_srcu); EXPORT_SYMBOL_GPL(synchronize_srcu);
/** /**
* synchronize_srcu_expedited - like synchronize_srcu, but less patient * synchronize_srcu_expedited - Brute-force SRCU grace period
* @sp: srcu_struct with which to synchronize. * @sp: srcu_struct with which to synchronize.
* *
* Flip the completed counter, and wait for the old count to drain to zero. * Wait for an SRCU grace period to elapse, but use a "big hammer"
* As with classic RCU, the updater must use some separate means of * approach to force the grace period to end quickly. This consumes
* synchronizing concurrent updates. Can block; must be called from * significant time on all CPUs and is unfriendly to real-time workloads,
* process context. * so is thus not recommended for any sort of common-case code. In fact,
* if you are using synchronize_srcu_expedited() in a loop, please
* restructure your code to batch your updates, and then use a single
* synchronize_srcu() instead.
* *
* Note that it is illegal to call synchronize_srcu_expedited() * Note that it is illegal to call this function while holding any lock
* from the corresponding SRCU read-side critical section; doing so * that is acquired by a CPU-hotplug notifier. And yes, it is also illegal
* will result in deadlock. However, it is perfectly legal to call * to call this function from a CPU-hotplug notifier. Failing to observe
* synchronize_srcu_expedited() on one srcu_struct from some other * these restriction will result in deadlock. It is also illegal to call
* srcu_struct's read-side critical section. * synchronize_srcu_expedited() from the corresponding SRCU read-side
* critical section; doing so will result in deadlock. However, it is
* perfectly legal to call synchronize_srcu_expedited() on one srcu_struct
* from some other srcu_struct's read-side critical section, as long as
* the resulting graph of srcu_structs is acyclic.
*/ */
void synchronize_srcu_expedited(struct srcu_struct *sp) void synchronize_srcu_expedited(struct srcu_struct *sp)
{ {
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment