| 1 | Userspace RCU API |
| 2 | ================= |
| 3 | |
| 4 | by Mathieu Desnoyers and Paul E. McKenney |
| 5 | |
| 6 | |
| 7 | API |
| 8 | --- |
| 9 | |
| 10 | ```c |
| 11 | void rcu_init(void); |
| 12 | ``` |
| 13 | |
| 14 | This must be called before any of the following functions |
| 15 | are invoked. |
| 16 | |
| 17 | |
| 18 | ```c |
| 19 | void rcu_read_lock(void); |
| 20 | ``` |
| 21 | |
| 22 | Begin an RCU read-side critical section. These critical |
| 23 | sections may be nested. |
| 24 | |
| 25 | |
| 26 | ```c |
| 27 | void rcu_read_unlock(void); |
| 28 | ``` |
| 29 | |
| 30 | End an RCU read-side critical section. |
| 31 | |
| 32 | |
| 33 | ```c |
| 34 | void rcu_register_thread(void); |
| 35 | ``` |
| 36 | |
| 37 | Each thread must invoke this function before its first call to |
| 38 | `rcu_read_lock()`. Threads that never call `rcu_read_lock()` need |
| 39 | not invoke this function. In addition, `rcu-bp` ("bullet proof" |
| 40 | RCU) does not require any thread to invoke `rcu_register_thread()`. |
| 41 | |
| 42 | |
| 43 | ```c |
| 44 | void rcu_unregister_thread(void); |
| 45 | ``` |
| 46 | |
| 47 | Each thread that invokes `rcu_register_thread()` must invoke |
| 48 | `rcu_unregister_thread()` before `invoking pthread_exit()` |
| 49 | or before returning from its top-level function. |
| 50 | |
| 51 | |
| 52 | ```c |
| 53 | void synchronize_rcu(void); |
| 54 | ``` |
| 55 | |
| 56 | Wait until every pre-existing RCU read-side critical section |
| 57 | has completed. Note that this primitive will not necessarily |
| 58 | wait for RCU read-side critical sections that have not yet |
| 59 | started: this is not a reader-writer lock. The duration |
| 60 | actually waited is called an RCU grace period. |
| 61 | |
| 62 | |
| 63 | ```c |
| 64 | void call_rcu(struct rcu_head *head, |
| 65 | void (*func)(struct rcu_head *head)); |
| 66 | ``` |
| 67 | |
| 68 | Registers the callback indicated by "head". This means |
| 69 | that `func` will be invoked after the end of a future |
| 70 | RCU grace period. The `rcu_head` structure referenced |
| 71 | by `head` will normally be a field in a larger RCU-protected |
| 72 | structure. A typical implementation of `func` is as |
| 73 | follows: |
| 74 | |
| 75 | ```c |
| 76 | void func(struct rcu_head *head) |
| 77 | { |
| 78 | struct foo *p = container_of(head, struct foo, rcu); |
| 79 | |
| 80 | free(p); |
| 81 | } |
| 82 | ``` |
| 83 | |
| 84 | This RCU callback function can be registered as follows |
| 85 | given a pointer `p` to the enclosing structure: |
| 86 | |
| 87 | ```c |
| 88 | call_rcu(&p->rcu, func); |
| 89 | ``` |
| 90 | |
| 91 | `call_rcu` should be called from registered RCU read-side threads. |
| 92 | For the QSBR flavor, the caller should be online. |
| 93 | |
| 94 | |
| 95 | ```c |
| 96 | void rcu_barrier(void); |
| 97 | ``` |
| 98 | |
| 99 | Wait for all `call_rcu()` work initiated prior to `rcu_barrier()` by |
| 100 | _any_ thread on the system to have completed before `rcu_barrier()` |
| 101 | returns. `rcu_barrier()` should never be called from a `call_rcu()` |
| 102 | thread. This function can be used, for instance, to ensure that |
| 103 | all memory reclaim involving a shared object has completed |
| 104 | before allowing `dlclose()` of this shared object to complete. |
| 105 | |
| 106 | |
| 107 | ```c |
| 108 | struct call_rcu_data *create_call_rcu_data(unsigned long flags, |
| 109 | int cpu_affinity); |
| 110 | ``` |
| 111 | |
| 112 | Returns a handle that can be passed to the following |
| 113 | primitives. The `flags` argument can be zero, or can be |
| 114 | `URCU_CALL_RCU_RT` if the worker threads associated with the |
| 115 | new helper thread are to get real-time response. The argument |
| 116 | `cpu_affinity` specifies a CPU on which the `call_rcu` thread should |
| 117 | be affined to. It is ignored if negative. |
| 118 | |
| 119 | |
| 120 | ```c |
| 121 | void call_rcu_data_free(struct call_rcu_data *crdp); |
| 122 | ``` |
| 123 | |
| 124 | Terminates a `call_rcu()` helper thread and frees its associated |
| 125 | data. The caller must have ensured that this thread is no longer |
| 126 | in use, for example, by passing `NULL` to `set_thread_call_rcu_data()` |
| 127 | and `set_cpu_call_rcu_data()` as required. |
| 128 | |
| 129 | |
| 130 | ```c |
| 131 | struct call_rcu_data *get_default_call_rcu_data(void); |
| 132 | ``` |
| 133 | |
| 134 | Returns the handle for the default `call_rcu()` helper thread. |
| 135 | Creates it if necessary. |
| 136 | |
| 137 | |
| 138 | ```c |
| 139 | struct call_rcu_data *get_cpu_call_rcu_data(int cpu); |
| 140 | ``` |
| 141 | |
| 142 | Returns the handle for the current CPU's `call_rcu()` helper |
| 143 | thread, or `NULL` if the current CPU has no helper thread |
| 144 | currently assigned. The call to this function and use of the |
| 145 | returned `call_rcu_data` should be protected by RCU read-side |
| 146 | lock. |
| 147 | |
| 148 | |
| 149 | ```c |
| 150 | struct call_rcu_data *get_thread_call_rcu_data(void); |
| 151 | ``` |
| 152 | |
| 153 | Returns the handle for the current thread's hard-assigned |
| 154 | `call_rcu()` helper thread, or `NULL` if the current thread is |
| 155 | instead using a per-CPU or the default helper thread. |
| 156 | |
| 157 | |
| 158 | ```c |
| 159 | struct call_rcu_data *get_call_rcu_data(void); |
| 160 | ``` |
| 161 | |
| 162 | Returns the handle for the current thread's `call_rcu()` helper |
| 163 | thread, which is either, in increasing order of preference: |
| 164 | per-thread hard-assigned helper thread, per-CPU helper thread, |
| 165 | or default helper thread. `get_call_rcu_data` should be called |
| 166 | from registered RCU read-side threads. For the QSBR flavor, the |
| 167 | caller should be online. |
| 168 | |
| 169 | |
| 170 | ```c |
| 171 | pthread_t get_call_rcu_thread(struct call_rcu_data *crdp); |
| 172 | ``` |
| 173 | |
| 174 | Returns the helper thread's pthread identifier linked to a call |
| 175 | rcu helper thread data. |
| 176 | |
| 177 | |
| 178 | ```c |
| 179 | void set_thread_call_rcu_data(struct call_rcu_data *crdp); |
| 180 | ``` |
| 181 | |
| 182 | Sets the current thread's hard-assigned `call_rcu()` helper to the |
| 183 | handle specified by `crdp`. Note that `crdp` can be `NULL` to |
| 184 | disassociate this thread from its helper. Once a thread is |
| 185 | disassociated from its helper, further `call_rcu()` invocations |
| 186 | use the current CPU's helper if there is one and the default |
| 187 | helper otherwise. |
| 188 | |
| 189 | |
| 190 | ```c |
| 191 | int set_cpu_call_rcu_data(int cpu, struct call_rcu_data *crdp); |
| 192 | ``` |
| 193 | |
| 194 | Sets the specified CPU's `call_rcu()` helper to the handle |
| 195 | specified by `crdp`. Again, `crdp` can be `NULL` to disassociate |
| 196 | this CPU from its helper thread. Once a CPU has been |
| 197 | disassociated from its helper, further `call_rcu()` invocations |
| 198 | that would otherwise have used this CPU's helper will instead |
| 199 | use the default helper. |
| 200 | |
| 201 | The caller must wait for a grace-period to pass between return from |
| 202 | `set_cpu_call_rcu_data()` and call to `call_rcu_data_free()` passing the |
| 203 | previous call rcu data as argument. |
| 204 | |
| 205 | |
| 206 | ```c |
| 207 | int create_all_cpu_call_rcu_data(unsigned long flags); |
| 208 | ``` |
| 209 | |
| 210 | Creates a separate `call_rcu()` helper thread for each CPU. |
| 211 | After this primitive is invoked, the global default `call_rcu()` |
| 212 | helper thread will not be called. |
| 213 | |
| 214 | The `set_thread_call_rcu_data()`, `set_cpu_call_rcu_data()`, and |
| 215 | `create_all_cpu_call_rcu_data()` functions may be combined to set up |
| 216 | pretty much any desired association between worker and `call_rcu()` |
| 217 | helper threads. If a given executable calls only `call_rcu()`, |
| 218 | then that executable will have only the single global default |
| 219 | `call_rcu()` helper thread. This will suffice in most cases. |
| 220 | |
| 221 | |
| 222 | ```c |
| 223 | void free_all_cpu_call_rcu_data(void); |
| 224 | ``` |
| 225 | |
| 226 | Clean up all the per-CPU `call_rcu` threads. Should be paired with |
| 227 | `create_all_cpu_call_rcu_data()` to perform teardown. Note that |
| 228 | this function invokes `synchronize_rcu()` internally, so the |
| 229 | caller should be careful not to hold mutexes (or mutexes within a |
| 230 | dependency chain) that are also taken within a RCU read-side |
| 231 | critical section, or in a section where QSBR threads are online. |
| 232 | |
| 233 | |
| 234 | ```c |
| 235 | void call_rcu_after_fork_child(void); |
| 236 | ``` |
| 237 | |
| 238 | Should be used as `pthread_atfork()` handler for programs using |
| 239 | `call_rcu` and performing `fork()` or `clone()` without a following |
| 240 | `exec()`. |