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