Lines Matching full:rcu
3 What is RCU? -- "Read, Copy, Update"
6 Please note that the "What is RCU?" LWN series is an excellent place
7 to start learning about RCU:
9 | 1. What is RCU, Fundamentally? https://lwn.net/Articles/262464/
10 | 2. What is RCU? Part 2: Usage https://lwn.net/Articles/263130/
11 | 3. RCU part 3: the RCU API https://lwn.net/Articles/264090/
12 | 4. The RCU API, 2010 Edition https://lwn.net/Articles/418853/
14 | 5. The RCU API, 2014 Edition https://lwn.net/Articles/609904/
16 | 6. The RCU API, 2019 Edition https://lwn.net/Articles/777036/
21 | 1. Unraveling RCU Mysteries: Fundamentals https://www.linuxfoundation.org/webinars/unrav…
22 | 2. Unraveling RCU Mysteries: Additional Use Cases https://www.linuxfoundation.org/webinars/unrav…
25 What is RCU?
27 RCU is a synchronization mechanism that was added to the Linux kernel
29 situations. Although RCU is actually quite simple, making effective use
32 describe and to use RCU. Instead, the experience has been that different
33 people must take different paths to arrive at an understanding of RCU,
37 :ref:`1. RCU OVERVIEW <1_whatisRCU>`
39 :ref:`2. WHAT IS RCU'S CORE API? <2_whatisRCU>`
41 :ref:`3. WHAT ARE SOME EXAMPLE USES OF CORE RCU API? <3_whatisRCU>`
45 :ref:`5. WHAT ARE SOME SIMPLE IMPLEMENTATIONS OF RCU? <5_whatisRCU>`
51 :ref:`8. FULL LIST OF RCU APIs <8_whatisRCU>`
60 understand the RCU implementation should focus on Section 5, then dive
73 1. RCU OVERVIEW
76 The basic idea behind RCU is to split updates into "removal" and
98 So the typical RCU update sequence goes something like the following:
103 b. Wait for all previous readers to complete their RCU read-side
110 Step (b) above is the key idea underlying RCU's deferred destruction.
111 The ability to wait until all readers are done allows RCU readers to
117 and must therefore exclude readers. In contrast, RCU-based updaters
121 readers. Concurrent RCU readers can then continue accessing the old
132 For example, RCU readers and updaters need not communicate at all,
133 but RCU provides implicit low-overhead communication between readers
138 Read on to learn about how RCU's API makes this easy.
142 2. WHAT IS RCU'S CORE API?
145 The core RCU API is quite small:
153 There are many other members of the RCU API, but the rest can be
157 The five core RCU APIs are described below, the other 18 will be enumerated
166 reclaimer that the reader is entering an RCU read-side critical
167 section. It is illegal to block while in an RCU read-side
169 can preempt RCU read-side critical sections. Any RCU-protected
170 data structure accessed during an RCU read-side critical section
173 with RCU to maintain longer-term references to data structures.
176 or interrupts also enters an RCU read-side critical section.
177 Acquiring a spinlock also enters an RCU read-side critical
180 Sleeplocks do *not* enter RCU read-side critical sections.
187 reclaimer that the reader is exiting an RCU read-side critical
189 or interrupts also exits an RCU read-side critical section.
190 Releasing a spinlock also exits an RCU read-side critical section.
192 Note that RCU read-side critical sections may be nested and/or
201 all pre-existing RCU read-side critical sections on all CPUs
203 necessarily wait for any subsequent RCU read-side critical
216 To reiterate, synchronize_rcu() waits only for ongoing RCU
221 **immediately** after the last pre-existing RCU read-side critical
223 delays. For another thing, many RCU implementations process
228 readers are done, its implementation is key to RCU. For RCU
235 argument which are invoked after all ongoing RCU read-side
259 RCU-protected pointer, in order to safely communicate the change
270 (1) which pointers are protected by RCU and (2) the point at which
283 an RCU-protected pointer, which returns a value that may
297 RCU-protected pointer to a local variable, then dereferences
309 RCU-protected structure, using the local variable is of
316 only within the enclosing RCU read-side critical section [1]_.
327 Holding a reference from one RCU read-side critical section
336 RCU, in particular, flagging a pointer that is subject to changing
343 of an RCU read-side critical section as long as the usage is
356 update-side code as well as by RCU readers, then an additional
359 the RCU lockdep code would complain only if this instance was
360 invoked outside of an RCU read-side critical section and without
387 The RCU infrastructure observes the temporal sequence of rcu_read_lock(),
391 implementations of the RCU infrastructure make heavy use of batching in
394 spatial changes via stores to and loads from the RCU-protected pointer in
397 There are at least three flavors of RCU usage in the Linux kernel. The diagram
419 a. RCU applied to normal data structures.
421 b. RCU applied to networking data structures that may be subjected
424 c. RCU applied to scheduler and interrupt/NMI-handler tasks.
427 for specialized uses, but are relatively uncommon. The SRCU, RCU-Tasks,
428 RCU-Tasks-Rude, and RCU-Tasks-Trace have similar relationships among
433 3. WHAT ARE SOME EXAMPLE USES OF CORE RCU API?
436 This section shows a simple use of the core RCU API to protect a
438 uses of RCU may be found in listRCU.rst and NMI-RCU.rst.
499 - Use rcu_read_lock() and rcu_read_unlock() to guard RCU
502 - Within an RCU read-side critical section, use rcu_dereference()
503 to dereference RCU-protected pointers.
508 - Use rcu_assign_pointer() to update an RCU-protected pointer.
515 RCU-protected data structure, but **before** reclaiming/freeing
517 RCU read-side critical sections that might be referencing that
520 See checklist.rst for additional rules to follow when using RCU.
521 And again, more-typical uses of RCU may be found in listRCU.rst
522 and NMI-RCU.rst.
547 struct rcu_head rcu;
577 call_rcu(&old_fp->rcu, foo_reclaim);
584 struct foo *fp = container_of(rp, struct foo, rcu);
598 RCU distinction between updater, namely foo_update_a(), and reclaimer,
605 RCU-protected data structure in order to register a callback
606 function that will be invoked after the completion of all RCU
614 kfree_rcu(old_fp, rcu);
624 Again, see checklist.rst for additional rules governing the use of RCU.
628 5. WHAT ARE SOME SIMPLE IMPLEMENTATIONS OF RCU?
631 One of the nice things about RCU is that it has extremely simple "toy"
634 presents two such "toy" implementations of RCU, one that is implemented
636 resembles "classic" RCU. Both are way too simple for real-world use,
638 in getting a feel for how RCU works. See kernel/rcu/update.c for a
643 for papers describing the Linux kernel RCU implementation. The OLS'01
650 This section presents a "toy" RCU implementation that is based on
684 don't forget about them when submitting patches making use of RCU!]::
701 that once synchronize_rcu() exits, all RCU read-side critical sections
712 from deadlock (an important property of RCU). The reason for this is
726 5B. "TOY" EXAMPLE #2: CLASSIC RCU
728 This section presents a "toy" RCU implementation that is based on
729 "classic RCU". It is also short on performance (but only for updates) and
748 This is the great strength of classic RCU in a non-preemptive kernel:
762 Remember that it is illegal to block while in an RCU read-side critical
764 that it must have completed all preceding RCU read-side critical sections.
766 RCU read-side critical sections will have completed.
770 that there are no RCU read-side critical sections holding a reference
776 Give an example where Classic RCU's read-side
784 If it is illegal to block in an RCU read-side
795 Although RCU can be used in many different ways, a very common use of
796 RCU is analogous to reader-writer locking. The following unified
797 diff shows how closely related RCU and reader-writer locking can be.
910 a single atomic update, converting to RCU will require special care.
912 Also, the presence of synchronize_rcu() means that the RCU version of
923 always the best way to think about using RCU. Another helpful analogy
924 considers RCU an effective reference count on everything which is
925 protected by RCU.
933 but with RCU the typical approach is to perform reads with SMP-aware
936 RCU provides a number of support functions that embed the required
951 which an RCU reference is held include:
959 The understanding that RCU provides a reference that only prevents a
961 slab cache marked ``SLAB_TYPESAFE_BY_RCU``. RCU operations may yield a
964 the same type. In this case RCU doesn't even protect the identity of the
980 passed to kref_put(). When RCU is being used, such finalization code
987 To see how to choose between these two analogies -- of RCU as a
988 reader-writer lock and RCU as a reference counting system -- it is useful
991 and shows how RCU can facilitate concurrency while elements are added
998 8. FULL LIST OF RCU APIs
1001 The RCU APIs are documented in docbook-format header comments in the
1006 RCU list traversal::
1030 RCU pointer/list update::
1054 RCU::
1094 RCU-Tasks::
1102 RCU-Tasks-Rude::
1110 RCU-Tasks-Trace::
1135 All: lockdep-checked RCU utility APIs::
1140 All: Unchecked RCU-protected pointer access::
1144 All: Unchecked RCU-protected pointer access with dereferencing prohibited::
1151 However, given that there are no fewer than four families of RCU APIs
1158 example, ftrace or BPF? If so, you need RCU-tasks,
1159 RCU-tasks-rude, and/or RCU-tasks-trace.
1170 or some other mechanism) as if they were explicit RCU readers?
1171 If so, RCU-sched readers are the only choice that will work
1172 for you, but since about v4.20 you use can use the vanilla RCU
1175 e. Do you need RCU grace periods to complete even in the face of
1180 use can use the vanilla RCU update primitives.
1183 RCU, but inappropriate for other synchronization mechanisms?
1190 and RCU Tasks Trace are the only choices that will work for you,
1193 h. Otherwise, use RCU.
1195 Of course, this all assumes that you have determined that RCU is in fact
1206 kernel? [Referring to the lock-based "toy" RCU
1234 Even in the absence of deadlock, this RCU implementation
1237 consider task A in an RCU read-side critical section
1241 read_acquire rcu_gp_mutex. Task A's RCU read-side
1245 Realtime RCU implementations therefore use a counter-based
1246 approach where tasks in RCU read-side critical sections
1252 Give an example where Classic RCU's read-side
1262 RCU allows such interrupt-disabling to be dispensed with.
1263 Thus, without RCU, you pay the cost of disabling interrupts,
1264 and with RCU you don't.
1266 One can argue that the overhead of RCU in this
1269 the overhead of RCU is merely zero, and that replacing
1271 with the zero-overhead RCU scheme does not constitute
1281 If it is illegal to block in an RCU read-side
1287 critical sections, it permits preemption of RCU
1289 spinlocks blocking while in RCU read-side critical
1293 possible to use priority boosting to keep the RCU
1313 For more information, see http://www.rdrop.com/users/paulmck/RCU.