Update following changes to sys_membarrier ABI
[urcu.git] / 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 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()`.
This page took 0.034531 seconds and 4 git commands to generate.