docs/devel/rcu.rst

1 Using RCU (Read-Copy-Update) for synchronization
4 Read-copy update (RCU) is a synchronization mechanism that is used to
5 protect read-mostly data structures.  RCU is very efficient and scalable
9 RCU supports concurrency between a single writer and multiple readers,
17 RCU is fundamentally a "wait-to-finish" mechanism.  The read side marks
25 the updater.  This is the reason why RCU is more scalable than,
27 the system will have a single instance of the RCU mechanism; a single
44     enter RCU crit.sec.
47            |                      |                    enter RCU crit.sec.
48     exit RCU crit.sec             |                           |
51                                                        exit RCU crit.sec.
60 RCU API
63 The core RCU API is small:
67         entering an RCU read-side critical section.
71         exiting an RCU read-side critical section.  Note that RCU
75         Blocks until all pre-existing RCU read-side critical sections
86         This function invokes ``func(head)`` after all pre-existing RCU
95                 struct rcu_head rcu;
104             call_rcu1(&foo.rcu, foo_reclaim);
108                 struct foo *fp = container_of(rp, struct foo, rcu);
125             g_free_rcu(&foo, rcu);
132         ``qatomic_rcu_read`` assumes that whenever a single RCU critical
135         case when using RCU, because read-side critical sections typically
140         RCU read-side critical sections must use ``qatomic_rcu_read()`` to
144         Furthermore, RCU read-side critical sections should traverse the
156         case when initializing a new copy of the RCU-protected data
160         order as reads in the RCU read-side critical sections (or if
164 The following APIs must be used before RCU is used in a thread:
167         Mark a thread as taking part in the RCU mechanism.  Such a thread
172         Mark a thread as not taking part anymore in the RCU mechanism.
198 - Waiting on a mutex is possible, though discouraged, within an RCU critical
200   programming; not allowing this would prevent upgrading an RCU read-side
212 RCU Patterns
215 Many patterns using read-writer locks translate directly to RCU, with
218 In general, RCU can be used whenever it is possible to create a new
230 Here are some frequently-used RCU idioms that are worth noting.
233 RCU list processing
239 RCU reference counting
242 Because grace periods are not allowed to complete while there is an RCU
243 read-side critical section in progress, the RCU read-side primitives
252 The RCU read-side critical section ensures that the value of ``p`` remains
289     call_rcu(foo_unref, old, rcu);
299             call_rcu(foo_destroy, p, rcu);
329 RCU resizable arrays
332 Resizable arrays can be used with RCU.  The expensive RCU synchronization
394 * The `Linux kernel RCU documentation <https://docs.kernel.org/RCU/>`__