doc/rcu-api.md

   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 struct urcu_gp_poll_state start_poll_synchronize_rcu(void);
  65 ```
  66
  67 Start polling on grace period. The returned poll state should be
  68 queried using `poll_state_synchronize_rcu` to check whether the
  69 grace period has completed.
  70
  71 `start_poll_synchronize_rcu` should be called from registered RCU
  72 read-side threads.  For the QSBR flavor, the caller should be online.
  73
  74
  75 ```c
  76 bool poll_state_synchronize_rcu(struct urcu_gp_poll_state state);
  77 ```
  78
  79 Poll the grace period state. Return true if quiescence was reached since
  80 the grace period was started, return false otherwise.
  81
  82
  83 ```c
  84 void call_rcu(struct rcu_head *head,
  85               void (*func)(struct rcu_head *head));
  86 ```
  87
  88 Registers the callback indicated by "head". This means
  89 that `func` will be invoked after the end of a future
  90 RCU grace period. The `rcu_head` structure referenced
  91 by `head` will normally be a field in a larger RCU-protected
  92 structure. A typical implementation of `func` is as
  93 follows:
  94
  95 ```c
  96 void func(struct rcu_head *head)
  97 {
  98     struct foo *p = container_of(head, struct foo, rcu);
  99
 100     free(p);
 101 }
 102 ```
 103
 104 This RCU callback function can be registered as follows
 105 given a pointer `p` to the enclosing structure:
 106
 107 ```c
 108 call_rcu(&p->rcu, func);
 109 ```
 110
 111 `call_rcu` should be called from registered RCU read-side threads.
 112 For the QSBR flavor, the caller should be online.
 113
 114
 115 ```c
 116 void rcu_barrier(void);
 117 ```
 118
 119 Wait for all `call_rcu()` work initiated prior to `rcu_barrier()` by
 120 _any_ thread on the system to have completed before `rcu_barrier()`
 121 returns. `rcu_barrier()` should never be called from a `call_rcu()`
 122 thread. This function can be used, for instance, to ensure that
 123 all memory reclaim involving a shared object has completed
 124 before allowing `dlclose()` of this shared object to complete.
 125
 126
 127 ```c
 128 struct call_rcu_data *create_call_rcu_data(unsigned long flags,
 129                                            int cpu_affinity);
 130 ```
 131
 132 Returns a handle that can be passed to the following
 133 primitives. The `flags` argument can be zero, or can be
 134 `URCU_CALL_RCU_RT` if the worker threads associated with the
 135 new helper thread are to get real-time response. The argument
 136 `cpu_affinity` specifies a CPU on which the `call_rcu` thread should
 137 be affined to. It is ignored if negative.
 138
 139
 140 ```c
 141 void call_rcu_data_free(struct call_rcu_data *crdp);
 142 ```
 143
 144 Terminates a `call_rcu()` helper thread and frees its associated
 145 data. The caller must have ensured that this thread is no longer
 146 in use, for example, by passing `NULL` to `set_thread_call_rcu_data()`
 147 and `set_cpu_call_rcu_data()` as required.
 148
 149
 150 ```c
 151 struct call_rcu_data *get_default_call_rcu_data(void);
 152 ```
 153
 154 Returns the handle for the default `call_rcu()` helper thread.
 155 Creates it if necessary.
 156
 157
 158 ```c
 159 struct call_rcu_data *get_cpu_call_rcu_data(int cpu);
 160 ```
 161
 162 Returns the handle for the current CPU's `call_rcu()` helper
 163 thread, or `NULL` if the current CPU has no helper thread
 164 currently assigned. The call to this function and use of the
 165 returned `call_rcu_data` should be protected by RCU read-side
 166 lock.
 167
 168
 169 ```c
 170 struct call_rcu_data *get_thread_call_rcu_data(void);
 171 ```
 172
 173 Returns the handle for the current thread's hard-assigned
 174 `call_rcu()` helper thread, or `NULL` if the current thread is
 175 instead using a per-CPU or the default helper thread.
 176
 177
 178 ```c
 179 struct call_rcu_data *get_call_rcu_data(void);
 180 ```
 181
 182 Returns the handle for the current thread's `call_rcu()` helper
 183 thread, which is either, in increasing order of preference:
 184 per-thread hard-assigned helper thread, per-CPU helper thread,
 185 or default helper thread. `get_call_rcu_data` should be called
 186 from registered RCU read-side threads. For the QSBR flavor, the
 187 caller should be online.
 188
 189
 190 ```c
 191 pthread_t get_call_rcu_thread(struct call_rcu_data *crdp);
 192 ```
 193
 194 Returns the helper thread's pthread identifier linked to a call
 195 rcu helper thread data.
 196
 197
 198 ```c
 199 void set_thread_call_rcu_data(struct call_rcu_data *crdp);
 200 ```
 201
 202 Sets the current thread's hard-assigned `call_rcu()` helper to the
 203 handle specified by `crdp`. Note that `crdp` can be `NULL` to
 204 disassociate this thread from its helper. Once a thread is
 205 disassociated from its helper, further `call_rcu()` invocations
 206 use the current CPU's helper if there is one and the default
 207 helper otherwise.
 208
 209
 210 ```c
 211 int set_cpu_call_rcu_data(int cpu, struct call_rcu_data *crdp);
 212 ```
 213
 214 Sets the specified CPU's `call_rcu()` helper to the handle
 215 specified by `crdp`. Again, `crdp` can be `NULL` to disassociate
 216 this CPU from its helper thread. Once a CPU has been
 217 disassociated from its helper, further `call_rcu()` invocations
 218 that would otherwise have used this CPU's helper will instead
 219 use the default helper.
 220
 221 The caller must wait for a grace-period to pass between return from
 222 `set_cpu_call_rcu_data()` and call to `call_rcu_data_free()` passing the
 223 previous call rcu data as argument.
 224
 225
 226 ```c
 227 int create_all_cpu_call_rcu_data(unsigned long flags);
 228 ```
 229
 230 Creates a separate `call_rcu()` helper thread for each CPU.
 231 After this primitive is invoked, the global default `call_rcu()`
 232 helper thread will not be called.
 233
 234 The `set_thread_call_rcu_data()`, `set_cpu_call_rcu_data()`, and
 235 `create_all_cpu_call_rcu_data()` functions may be combined to set up
 236 pretty much any desired association between worker and `call_rcu()`
 237 helper threads. If a given executable calls only `call_rcu()`,
 238 then that executable will have only the single global default
 239 `call_rcu()` helper thread. This will suffice in most cases.
 240
 241
 242 ```c
 243 void free_all_cpu_call_rcu_data(void);
 244 ```
 245
 246 Clean up all the per-CPU `call_rcu` threads. Should be paired with
 247 `create_all_cpu_call_rcu_data()` to perform teardown. Note that
 248 this function invokes `synchronize_rcu()` internally, so the
 249 caller should be careful not to hold mutexes (or mutexes within a
 250 dependency chain) that are also taken within a RCU read-side
 251 critical section, or in a section where QSBR threads are online.
 252
 253
 254 ```c
 255 void call_rcu_before_fork_parent(void);
 256 void call_rcu_after_fork_parent(void);
 257 void call_rcu_after_fork_child(void);
 258 ```
 259
 260 Should be used as `pthread_atfork()` handler for programs using
 261 `call_rcu` and performing `fork()` or `clone()` without a following
 262 `exec()`.