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