[PATCH] RCU documentation: self-limiting updates and call_rcu()

An update to the RCU documentation calling out the
self-limiting-update-rate advantages of synchronize_rcu(), and describing
how to use call_rcu() in a way that results in self-limiting updates.
Self-limiting updates are important to avoiding RCU-induced OOM in face of
denial-of-service attacks.

Signed-off-by: Paul E. McKenney <paulmck@us.ibm.com>
Signed-off-by: Andrew Morton <akpm@osdl.org>
Signed-off-by: Linus Torvalds <torvalds@osdl.org>

1 files changed, 11 insertions, 1 deletions

diff --git a/Documentation/RCU/whatisRCU.txt b/Documentation/RCU/whatisRCU.txt
index 6e459420ee9f..4f41a60e5111 100644
--- a/Documentation/RCU/whatisRCU.txt
+++ b/Documentation/RCU/whatisRCU.txt
@@ -184,7 +184,17 @@ synchronize_rcu()
         blocking, it registers a function and argument which are invoked
         after all ongoing RCU read-side critical sections have completed.
         This callback variant is particularly useful in situations where
-        it is illegal to block.
+        it is illegal to block or where update-side performance is
+        critically important.
+
+        However, the call_rcu() API should not be used lightly, as use
+        of the synchronize_rcu() API generally results in simpler code.
+        In addition, the synchronize_rcu() API has the nice property
+        of automatically limiting update rate should grace periods
+        be delayed.  This property results in system resilience in face
+        of denial-of-service attacks.  Code using call_rcu() should limit
+        update rate in order to gain this same sort of resilience.  See
+        checklist.txt for some approaches to limiting the update rate.
 
 rcu_assign_pointer()