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