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
990 passed to kref_put(). When RCU is being used, such finalization code
997 To see how to choose between these two analogies -- of RCU as a
998 reader-writer lock and RCU as a reference counting system -- it is useful
1001 and shows how RCU can facilitate concurrency while elements are added
1008 8. FULL LIST OF RCU APIs
1011 The RCU APIs are documented in docbook-format header comments in the
1016 RCU list traversal::
1040 RCU pointer/list update::
1064 RCU::
1104 RCU-Tasks::
1112 RCU-Tasks-Rude::
1120 RCU-Tasks-Trace::
1145 All: lockdep-checked RCU utility APIs::
1150 All: Unchecked RCU-protected pointer access::
1154 All: Unchecked RCU-protected pointer access with dereferencing prohibited::
1161 However, given that there are no fewer than four families of RCU APIs
1168 example, ftrace or BPF? If so, you need RCU-tasks,
1169 RCU-tasks-rude, and/or RCU-tasks-trace.
1180 or some other mechanism) as if they were explicit RCU readers?
1181 If so, RCU-sched readers are the only choice that will work
1182 for you, but since about v4.20 you use can use the vanilla RCU
1185 e. Do you need RCU grace periods to complete even in the face of
1190 use can use the vanilla RCU update primitives.
1193 RCU, but inappropriate for other synchronization mechanisms?
1200 and RCU Tasks Trace are the only choices that will work for you,
1203 h. Otherwise, use RCU.
1205 Of course, this all assumes that you have determined that RCU is in fact
1216 kernel? [Referring to the lock-based "toy" RCU
1244 Even in the absence of deadlock, this RCU implementation
1247 consider task A in an RCU read-side critical section
1251 read_acquire rcu_gp_mutex. Task A's RCU read-side
1255 Realtime RCU implementations therefore use a counter-based
1256 approach where tasks in RCU read-side critical sections
1262 Give an example where Classic RCU's read-side
1272 RCU allows such interrupt-disabling to be dispensed with.
1273 Thus, without RCU, you pay the cost of disabling interrupts,
1274 and with RCU you don't.
1276 One can argue that the overhead of RCU in this
1279 the overhead of RCU is merely zero, and that replacing
1281 with the zero-overhead RCU scheme does not constitute
1291 If it is illegal to block in an RCU read-side
1297 critical sections, it permits preemption of RCU
1299 spinlocks blocking while in RCU read-side critical
1303 possible to use priority boosting to keep the RCU
1323 For more information, see http://www.rdrop.com/users/paulmck/RCU.