rcu: Remove list_for_each_continue_rcu()
[linux-3.10.git] / Documentation / RCU / whatisRCU.txt
index e04d643..9d30de0 100644 (file)
@@ -4,6 +4,7 @@ to start learning about RCU:
 1.     What is RCU, Fundamentally?  http://lwn.net/Articles/262464/
 2.     What is RCU? Part 2: Usage   http://lwn.net/Articles/263130/
 3.     RCU part 3: the RCU API      http://lwn.net/Articles/264090/
+4.     The RCU API, 2010 Edition    http://lwn.net/Articles/418853/
 
 
 What is RCU?
@@ -136,10 +137,10 @@ rcu_read_lock()
        Used by a reader to inform the reclaimer that the reader is
        entering an RCU read-side critical section.  It is illegal
        to block while in an RCU read-side critical section, though
-       kernels built with CONFIG_PREEMPT_RCU can preempt RCU read-side
-       critical sections.  Any RCU-protected data structure accessed
-       during an RCU read-side critical section is guaranteed to remain
-       unreclaimed for the full duration of that critical section.
+       kernels built with CONFIG_TREE_PREEMPT_RCU can preempt RCU
+       read-side critical sections.  Any RCU-protected data structure
+       accessed during an RCU read-side critical section is guaranteed to
+       remain unreclaimed for the full duration of that critical section.
        Reference counts may be used in conjunction with RCU to maintain
        longer-term references to data structures.
 
@@ -323,14 +324,17 @@ used as follows:
        Defer                   Protect
 
 a.     synchronize_rcu()       rcu_read_lock() / rcu_read_unlock()
-       call_rcu()
+       call_rcu()              rcu_dereference()
 
 b.     call_rcu_bh()           rcu_read_lock_bh() / rcu_read_unlock_bh()
+                               rcu_dereference_bh()
 
-c.     synchronize_sched()     preempt_disable() / preempt_enable()
+c.     synchronize_sched()     rcu_read_lock_sched() / rcu_read_unlock_sched()
+                               preempt_disable() / preempt_enable()
                                local_irq_save() / local_irq_restore()
                                hardirq enter / hardirq exit
                                NMI enter / NMI exit
+                               rcu_dereference_sched()
 
 These three mechanisms are used as follows:
 
@@ -780,16 +784,12 @@ Linux-kernel source code, but it helps to have a full list of the
 APIs, since there does not appear to be a way to categorize them
 in docbook.  Here is the list, by category.
 
-RCU pointer/list traversal:
+RCU list traversal:
 
-       rcu_dereference
        list_for_each_entry_rcu
        hlist_for_each_entry_rcu
-
-       list_for_each_rcu               (to be deprecated in favor of
-                                        list_for_each_entry_rcu)
-       list_for_each_continue_rcu      (to be deprecated in favor of new
-                                        list_for_each_entry_continue_rcu)
+       hlist_nulls_for_each_entry_rcu
+       list_for_each_entry_continue_rcu
 
 RCU pointer/list update:
 
@@ -809,30 +809,89 @@ RCU:      Critical sections       Grace period            Barrier
 
        rcu_read_lock           synchronize_net         rcu_barrier
        rcu_read_unlock         synchronize_rcu
+       rcu_dereference         synchronize_rcu_expedited
                                call_rcu
 
 
 bh:    Critical sections       Grace period            Barrier
 
        rcu_read_lock_bh        call_rcu_bh             rcu_barrier_bh
-       rcu_read_unlock_bh
+       rcu_read_unlock_bh      synchronize_rcu_bh
+       rcu_dereference_bh      synchronize_rcu_bh_expedited
 
 
 sched: Critical sections       Grace period            Barrier
 
-       [preempt_disable]       synchronize_sched       rcu_barrier_sched
-       [and friends]           call_rcu_sched
+       rcu_read_lock_sched     synchronize_sched       rcu_barrier_sched
+       rcu_read_unlock_sched   call_rcu_sched
+       [preempt_disable]       synchronize_sched_expedited
+       [and friends]
+       rcu_dereference_sched
 
 
 SRCU:  Critical sections       Grace period            Barrier
 
-       srcu_read_lock          synchronize_srcu        N/A
-       srcu_read_unlock
+       srcu_read_lock          synchronize_srcu        srcu_barrier
+       srcu_read_unlock        call_srcu
+       srcu_read_lock_raw      synchronize_srcu_expedited
+       srcu_read_unlock_raw
+       srcu_dereference
+
+SRCU:  Initialization/cleanup
+       init_srcu_struct
+       cleanup_srcu_struct
 
+All:  lockdep-checked RCU-protected pointer access
+
+       rcu_dereference_check
+       rcu_dereference_protected
+       rcu_access_pointer
 
 See the comment headers in the source code (or the docbook generated
 from them) for more information.
 
+However, given that there are no fewer than four families of RCU APIs
+in the Linux kernel, how do you choose which one to use?  The following
+list can be helpful:
+
+a.     Will readers need to block?  If so, you need SRCU.
+
+b.     Is it necessary to start a read-side critical section in a
+       hardirq handler or exception handler, and then to complete
+       this read-side critical section in the task that was
+       interrupted?  If so, you need SRCU's srcu_read_lock_raw() and
+       srcu_read_unlock_raw() primitives.
+
+c.     What about the -rt patchset?  If readers would need to block
+       in an non-rt kernel, you need SRCU.  If readers would block
+       in a -rt kernel, but not in a non-rt kernel, SRCU is not
+       necessary.
+
+d.     Do you need to treat NMI handlers, hardirq handlers,
+       and code segments with preemption disabled (whether
+       via preempt_disable(), local_irq_save(), local_bh_disable(),
+       or some other mechanism) as if they were explicit RCU readers?
+       If so, RCU-sched is the only choice that will work for you.
+
+e.     Do you need RCU grace periods to complete even in the face
+       of softirq monopolization of one or more of the CPUs?  For
+       example, is your code subject to network-based denial-of-service
+       attacks?  If so, you need RCU-bh.
+
+f.     Is your workload too update-intensive for normal use of
+       RCU, but inappropriate for other synchronization mechanisms?
+       If so, consider SLAB_DESTROY_BY_RCU.  But please be careful!
+
+g.     Do you need read-side critical sections that are respected
+       even though they are in the middle of the idle loop, during
+       user-mode execution, or on an offlined CPU?  If so, SRCU is the
+       only choice that will work for you.
+
+h.     Otherwise, use RCU.
+
+Of course, this all assumes that you have determined that RCU is in fact
+the right tool for your job.
+
 
 8.  ANSWERS TO QUICK QUIZZES