aboutsummaryrefslogtreecommitdiff
path: root/docs/devel/rcu.txt
blob: cdf002edd82625c2a322cdab797c1b521c24d311 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
Using RCU (Read-Copy-Update) for synchronization
================================================

Read-copy update (RCU) is a synchronization mechanism that is used to
protect read-mostly data structures.  RCU is very efficient and scalable
on the read side (it is wait-free), and thus can make the read paths
extremely fast.

RCU supports concurrency between a single writer and multiple readers,
thus it is not used alone.  Typically, the write-side will use a lock to
serialize multiple updates, but other approaches are possible (e.g.,
restricting updates to a single task).  In QEMU, when a lock is used,
this will often be the "iothread mutex", also known as the "big QEMU
lock" (BQL).  Also, restricting updates to a single task is done in
QEMU using the "bottom half" API.

RCU is fundamentally a "wait-to-finish" mechanism.  The read side marks
sections of code with "critical sections", and the update side will wait
for the execution of all *currently running* critical sections before
proceeding, or before asynchronously executing a callback.

The key point here is that only the currently running critical sections
are waited for; critical sections that are started _after_ the beginning
of the wait do not extend the wait, despite running concurrently with
the updater.  This is the reason why RCU is more scalable than,
for example, reader-writer locks.  It is so much more scalable that
the system will have a single instance of the RCU mechanism; a single
mechanism can be used for an arbitrary number of "things", without
having to worry about things such as contention or deadlocks.

How is this possible?  The basic idea is to split updates in two phases,
"removal" and "reclamation".  During removal, we ensure that subsequent
readers will not be able to get a reference to the old data.  After
removal has completed, a critical section will not be able to access
the old data.  Therefore, critical sections that begin after removal
do not matter; as soon as all previous critical sections have finished,
there cannot be any readers who hold references to the data structure,
and these can now be safely reclaimed (e.g., freed or unref'ed).

Here is a picture:

        thread 1                  thread 2                  thread 3
    -------------------    ------------------------    -------------------
    enter RCU crit.sec.
           |                finish removal phase
           |                begin wait
           |                      |                    enter RCU crit.sec.
    exit RCU crit.sec             |                           |
                            complete wait                     |
                            begin reclamation phase           |
                                                       exit RCU crit.sec.


Note how thread 3 is still executing its critical section when thread 2
starts reclaiming data.  This is possible, because the old version of the
data structure was not accessible at the time thread 3 began executing
that critical section.


RCU API
=======

The core RCU API is small:

     void rcu_read_lock(void);

        Used by a reader to inform the reclaimer that the reader is
        entering an RCU read-side critical section.

     void rcu_read_unlock(void);

        Used by a reader to inform the reclaimer that the reader is
        exiting an RCU read-side critical section.  Note that RCU
        read-side critical sections may be nested and/or overlapping.

     void synchronize_rcu(void);

        Blocks until all pre-existing RCU read-side critical sections
        on all threads have completed.  This marks the end of the removal
        phase and the beginning of reclamation phase.

        Note that it would be valid for another update to come while
        synchronize_rcu is running.  Because of this, it is better that
        the updater releases any locks it may hold before calling
        synchronize_rcu.  If this is not possible (for example, because
        the updater is protected by the BQL), you can use call_rcu.

     void call_rcu1(struct rcu_head * head,
                    void (*func)(struct rcu_head *head));

        This function invokes func(head) after all pre-existing RCU
        read-side critical sections on all threads have completed.  This
        marks the end of the removal phase, with func taking care
        asynchronously of the reclamation phase.

        The foo struct needs to have an rcu_head structure added,
        perhaps as follows:

            struct foo {
                struct rcu_head rcu;
                int a;
                char b;
                long c;
            };

        so that the reclaimer function can fetch the struct foo address
        and free it:

            call_rcu1(&foo.rcu, foo_reclaim);

            void foo_reclaim(struct rcu_head *rp)
            {
                struct foo *fp = container_of(rp, struct foo, rcu);
                g_free(fp);
            }

        For the common case where the rcu_head member is the first of the
        struct, you can use the following macro.

     void call_rcu(T *p,
                   void (*func)(T *p),
                   field-name);
     void g_free_rcu(T *p,
                     field-name);

        call_rcu1 is typically used through these macro, in the common case
        where the "struct rcu_head" is the first field in the struct.  If
        the callback function is g_free, in particular, g_free_rcu can be
        used.  In the above case, one could have written simply:

            g_free_rcu(&foo, rcu);

     typeof(*p) qatomic_rcu_read(p);

        qatomic_rcu_read() is similar to qatomic_load_acquire(), but it makes
        some assumptions on the code that calls it.  This allows a more
        optimized implementation.

        qatomic_rcu_read assumes that whenever a single RCU critical
        section reads multiple shared data, these reads are either
        data-dependent or need no ordering.  This is almost always the
        case when using RCU, because read-side critical sections typically
        navigate one or more pointers (the pointers that are changed on
        every update) until reaching a data structure of interest,
        and then read from there.

        RCU read-side critical sections must use qatomic_rcu_read() to
        read data, unless concurrent writes are prevented by another
        synchronization mechanism.

        Furthermore, RCU read-side critical sections should traverse the
        data structure in a single direction, opposite to the direction
        in which the updater initializes it.

     void qatomic_rcu_set(p, typeof(*p) v);

        qatomic_rcu_set() is similar to qatomic_store_release(), though it also
        makes assumptions on the code that calls it in order to allow a more
        optimized implementation.

        In particular, qatomic_rcu_set() suffices for synchronization
        with readers, if the updater never mutates a field within a
        data item that is already accessible to readers.  This is the
        case when initializing a new copy of the RCU-protected data
        structure; just ensure that initialization of *p is carried out
        before qatomic_rcu_set() makes the data item visible to readers.
        If this rule is observed, writes will happen in the opposite
        order as reads in the RCU read-side critical sections (or if
        there is just one update), and there will be no need for other
        synchronization mechanism to coordinate the accesses.

The following APIs must be used before RCU is used in a thread:

     void rcu_register_thread(void);

        Mark a thread as taking part in the RCU mechanism.  Such a thread
        will have to report quiescent points regularly, either manually
        or through the QemuCond/QemuSemaphore/QemuEvent APIs.

     void rcu_unregister_thread(void);

        Mark a thread as not taking part anymore in the RCU mechanism.
        It is not a problem if such a thread reports quiescent points,
        either manually or by using the QemuCond/QemuSemaphore/QemuEvent
        APIs.

Note that these APIs are relatively heavyweight, and should _not_ be
nested.

Convenience macros
==================

Two macros are provided that automatically release the read lock at the
end of the scope.

      RCU_READ_LOCK_GUARD()

         Takes the lock and will release it at the end of the block it's
         used in.

      WITH_RCU_READ_LOCK_GUARD()  { code }

         Is used at the head of a block to protect the code within the block.

Note that 'goto'ing out of the guarded block will also drop the lock.

DIFFERENCES WITH LINUX
======================

- Waiting on a mutex is possible, though discouraged, within an RCU critical
  section.  This is because spinlocks are rarely (if ever) used in userspace
  programming; not allowing this would prevent upgrading an RCU read-side
  critical section to become an updater.

- qatomic_rcu_read and qatomic_rcu_set replace rcu_dereference and
  rcu_assign_pointer.  They take a _pointer_ to the variable being accessed.

- call_rcu is a macro that has an extra argument (the name of the first
  field in the struct, which must be a struct rcu_head), and expects the
  type of the callback's argument to be the type of the first argument.
  call_rcu1 is the same as Linux's call_rcu.


RCU PATTERNS
============

Many patterns using read-writer locks translate directly to RCU, with
the advantages of higher scalability and deadlock immunity.

In general, RCU can be used whenever it is possible to create a new
"version" of a data structure every time the updater runs.  This may
sound like a very strict restriction, however:

- the updater does not mean "everything that writes to a data structure",
  but rather "everything that involves a reclamation step".  See the
  array example below

- in some cases, creating a new version of a data structure may actually
  be very cheap.  For example, modifying the "next" pointer of a singly
  linked list is effectively creating a new version of the list.

Here are some frequently-used RCU idioms that are worth noting.


RCU list processing
-------------------

TBD (not yet used in QEMU)


RCU reference counting
----------------------

Because grace periods are not allowed to complete while there is an RCU
read-side critical section in progress, the RCU read-side primitives
may be used as a restricted reference-counting mechanism.  For example,
consider the following code fragment:

    rcu_read_lock();
    p = qatomic_rcu_read(&foo);
    /* do something with p. */
    rcu_read_unlock();

The RCU read-side critical section ensures that the value of "p" remains
valid until after the rcu_read_unlock().  In some sense, it is acquiring
a reference to p that is later released when the critical section ends.
The write side looks simply like this (with appropriate locking):

    qemu_mutex_lock(&foo_mutex);
    old = foo;
    qatomic_rcu_set(&foo, new);
    qemu_mutex_unlock(&foo_mutex);
    synchronize_rcu();
    free(old);

If the processing cannot be done purely within the critical section, it
is possible to combine this idiom with a "real" reference count:

    rcu_read_lock();
    p = qatomic_rcu_read(&foo);
    foo_ref(p);
    rcu_read_unlock();
    /* do something with p. */
    foo_unref(p);

The write side can be like this:

    qemu_mutex_lock(&foo_mutex);
    old = foo;
    qatomic_rcu_set(&foo, new);
    qemu_mutex_unlock(&foo_mutex);
    synchronize_rcu();
    foo_unref(old);

or with call_rcu:

    qemu_mutex_lock(&foo_mutex);
    old = foo;
    qatomic_rcu_set(&foo, new);
    qemu_mutex_unlock(&foo_mutex);
    call_rcu(foo_unref, old, rcu);

In both cases, the write side only performs removal.  Reclamation
happens when the last reference to a "foo" object is dropped.
Using synchronize_rcu() is undesirably expensive, because the
last reference may be dropped on the read side.  Hence you can
use call_rcu() instead:

     foo_unref(struct foo *p) {
        if (qatomic_fetch_dec(&p->refcount) == 1) {
            call_rcu(foo_destroy, p, rcu);
        }
    }


Note that the same idioms would be possible with reader/writer
locks:

    read_lock(&foo_rwlock);         write_mutex_lock(&foo_rwlock);
    p = foo;                        p = foo;
    /* do something with p. */      foo = new;
    read_unlock(&foo_rwlock);       free(p);
                                    write_mutex_unlock(&foo_rwlock);
                                    free(p);

    ------------------------------------------------------------------

    read_lock(&foo_rwlock);         write_mutex_lock(&foo_rwlock);
    p = foo;                        old = foo;
    foo_ref(p);                     foo = new;
    read_unlock(&foo_rwlock);       foo_unref(old);
    /* do something with p. */      write_mutex_unlock(&foo_rwlock);
    read_lock(&foo_rwlock);
    foo_unref(p);
    read_unlock(&foo_rwlock);

foo_unref could use a mechanism such as bottom halves to move deallocation
out of the write-side critical section.


RCU resizable arrays
--------------------

Resizable arrays can be used with RCU.  The expensive RCU synchronization
(or call_rcu) only needs to take place when the array is resized.
The two items to take care of are:

- ensuring that the old version of the array is available between removal
  and reclamation;

- avoiding mismatches in the read side between the array data and the
  array size.

The first problem is avoided simply by not using realloc.  Instead,
each resize will allocate a new array and copy the old data into it.
The second problem would arise if the size and the data pointers were
two members of a larger struct:

    struct mystuff {
        ...
        int data_size;
        int data_alloc;
        T   *data;
        ...
    };

Instead, we store the size of the array with the array itself:

    struct arr {
        int size;
        int alloc;
        T   data[];
    };
    struct arr *global_array;

    read side:
        rcu_read_lock();
        struct arr *array = qatomic_rcu_read(&global_array);
        x = i < array->size ? array->data[i] : -1;
        rcu_read_unlock();
        return x;

    write side (running under a lock):
        if (global_array->size == global_array->alloc) {
            /* Creating a new version.  */
            new_array = g_malloc(sizeof(struct arr) +
                                 global_array->alloc * 2 * sizeof(T));
            new_array->size = global_array->size;
            new_array->alloc = global_array->alloc * 2;
            memcpy(new_array->data, global_array->data,
                   global_array->alloc * sizeof(T));

            /* Removal phase.  */
            old_array = global_array;
            qatomic_rcu_set(&new_array->data, new_array);
            synchronize_rcu();

            /* Reclamation phase.  */
            free(old_array);
        }


SOURCES
=======

* Documentation/RCU/ from the Linux kernel