Commit | Line | Data |
---|---|---|
26ba798a PM |
1 | Userspace RCU API |
2 | by Mathieu Desnoyers and Paul E. McKenney | |
3 | ||
4 | ||
5 | void rcu_init(void); | |
6 | ||
7 | This must be called before any of the following functions | |
8 | are invoked. | |
9 | ||
10 | void rcu_read_lock(void); | |
11 | ||
12 | Begin an RCU read-side critical section. These critical | |
13 | sections may be nested. | |
14 | ||
15 | void rcu_read_unlock(void); | |
16 | ||
17 | End an RCU read-side critical section. | |
18 | ||
f9da0936 | 19 | void rcu_register_thread(void); |
26ba798a PM |
20 | |
21 | Each thread must invoke this function before its first call to | |
22 | rcu_read_lock(). Threads that never call rcu_read_lock() need | |
23 | not invoke this function. In addition, rcu-bp ("bullet proof" | |
24 | RCU) does not require any thread to invoke rcu_register_thread(). | |
25 | ||
f9da0936 | 26 | void rcu_unregister_thread(void); |
26ba798a PM |
27 | |
28 | Each thread that invokes rcu_register_thread() must invoke | |
29 | rcu_unregister_thread() before invoking pthread_exit() | |
30 | or before returning from its top-level function. | |
31 | ||
32 | void synchronize_rcu(void); | |
33 | ||
34 | Wait until every pre-existing RCU read-side critical section | |
35 | has completed. Note that this primitive will not necessarily | |
36 | wait for RCU read-side critical sections that have not yet | |
37 | started: this is not a reader-writer lock. The duration | |
38 | actually waited is called an RCU grace period. | |
39 | ||
40 | void call_rcu(struct rcu_head *head, | |
41 | void (*func)(struct rcu_head *head)); | |
42 | ||
43 | Registers the callback indicated by "head". This means | |
44 | that "func" will be invoked after the end of a future | |
45 | RCU grace period. The rcu_head structure referenced | |
46 | by "head" will normally be a field in a larger RCU-protected | |
47 | structure. A typical implementation of "func" is as | |
48 | follows: | |
49 | ||
50 | void func(struct rcu_head *head) | |
51 | { | |
52 | struct foo *p = container_of(head, struct foo, rcu); | |
53 | ||
54 | free(p); | |
55 | } | |
56 | ||
57 | This RCU callback function can be registered as follows | |
58 | given a pointer "p" to the enclosing structure: | |
59 | ||
60 | call_rcu(&p->rcu, func); | |
61 | ||
f9da0936 MD |
62 | call_rcu should be called from registered RCU read-side threads. |
63 | For the QSBR flavor, the caller should be online. | |
64 | ||
c1d2c60b MD |
65 | struct call_rcu_data *create_call_rcu_data(unsigned long flags, |
66 | int cpu_affinity); | |
26ba798a PM |
67 | |
68 | Returns a handle that can be passed to the following | |
69 | primitives. The "flags" argument can be zero, or can be | |
70 | URCU_CALL_RCU_RT if the worker threads associated with the | |
c1d2c60b MD |
71 | new helper thread are to get real-time response. The argument |
72 | "cpu_affinity" specifies a cpu on which the call_rcu thread should | |
73 | be affined to. It is ignored if negative. | |
26ba798a | 74 | |
f9da0936 MD |
75 | void call_rcu_data_free(struct call_rcu_data *crdp); |
76 | ||
77 | Terminates a call_rcu() helper thread and frees its associated | |
78 | data. The caller must have ensured that this thread is no longer | |
79 | in use, for example, by passing NULL to set_thread_call_rcu_data() | |
80 | and set_cpu_call_rcu_data() as required. | |
81 | ||
82 | struct call_rcu_data *get_default_call_rcu_data(void); | |
83 | ||
84 | Returns the handle for the default call_rcu() helper thread. | |
85 | Creates it if necessary. | |
86 | ||
87 | struct call_rcu_data *get_cpu_call_rcu_data(int cpu); | |
88 | ||
89 | Returns the handle for the current cpu's call_rcu() helper | |
90 | thread, or NULL if the current CPU has no helper thread | |
91 | currently assigned. The call to this function and use of the | |
92 | returned call_rcu_data should be protected by RCU read-side | |
93 | lock. | |
26ba798a PM |
94 | |
95 | struct call_rcu_data *get_thread_call_rcu_data(void); | |
96 | ||
97 | Returns the handle for the current thread's hard-assigned | |
98 | call_rcu() helper thread, or NULL if the current thread is | |
99 | instead using a per-CPU or the default helper thread. | |
100 | ||
f9da0936 MD |
101 | struct call_rcu_data *get_call_rcu_data(void); |
102 | ||
103 | Returns the handle for the current thread's call_rcu() helper | |
104 | thread, which is either, in increasing order of preference: | |
105 | per-thread hard-assigned helper thread, per-cpu helper thread, | |
b1f69e84 MD |
106 | or default helper thread. get_call_rcu_data should be called |
107 | from registered RCU read-side threads. For the QSBR flavor, the | |
108 | caller should be online. | |
f9da0936 MD |
109 | |
110 | pthread_t get_call_rcu_thread(struct call_rcu_data *crdp); | |
111 | ||
112 | Returns the helper thread's pthread identifier linked to a call | |
113 | rcu helper thread data. | |
114 | ||
26ba798a PM |
115 | void set_thread_call_rcu_data(struct call_rcu_data *crdp); |
116 | ||
117 | Sets the current thread's hard-assigned call_rcu() helper to the | |
118 | handle specified by "crdp". Note that "crdp" can be NULL to | |
119 | disassociate this thread from its helper. Once a thread is | |
120 | disassociated from its helper, further call_rcu() invocations | |
121 | use the current CPU's helper if there is one and the default | |
122 | helper otherwise. | |
123 | ||
124 | int set_cpu_call_rcu_data(int cpu, struct call_rcu_data *crdp); | |
125 | ||
126 | Sets the specified CPU's call_rcu() helper to the handle | |
127 | specified by "crdp". Again, "crdp" can be NULL to disassociate | |
128 | this CPU from its helper thread. Once a CPU has been | |
129 | disassociated from its helper, further call_rcu() invocations | |
130 | that would otherwise have used this CPU's helper will instead | |
f9da0936 MD |
131 | use the default helper. The caller must wait for a grace-period |
132 | to pass between return from set_cpu_call_rcu_data() and call to | |
133 | call_rcu_data_free() passing the previous call rcu data as | |
134 | argument. | |
26ba798a PM |
135 | |
136 | int create_all_cpu_call_rcu_data(unsigned long flags) | |
137 | ||
138 | Creates a separate call_rcu() helper thread for each CPU. | |
139 | After this primitive is invoked, the global default call_rcu() | |
140 | helper thread will not be called. | |
141 | ||
142 | The set_thread_call_rcu_data(), set_cpu_call_rcu_data(), and | |
143 | create_all_cpu_call_rcu_data() functions may be combined to set up | |
144 | pretty much any desired association between worker and call_rcu() | |
145 | helper threads. If a given executable calls only call_rcu(), | |
146 | then that executable will have only the single global default | |
147 | call_rcu() helper thread. This will suffice in most cases. | |
148 | ||
f9da0936 | 149 | void free_all_cpu_call_rcu_data(void); |
26ba798a | 150 | |
f9da0936 MD |
151 | Clean up all the per-CPU call_rcu threads. Should be paired with |
152 | create_all_cpu_call_rcu_data() to perform teardown. Note that | |
153 | this function invokes synchronize_rcu() internally, so the | |
154 | caller should be careful not to hold mutexes (or mutexes within a | |
155 | dependency chain) that are also taken within a RCU read-side | |
156 | critical section, or in a section where QSBR threads are online. | |
157 | ||
158 | void call_rcu_after_fork_child(void); | |
159 | ||
160 | Should be used as pthread_atfork() handler for programs using | |
161 | call_rcu and performing fork() or clone() without a following | |
162 | exec(). |