doc/examples: fix typo in list example
[urcu.git] / doc / rcu-api.txt
1 Userspace RCU API
2 by Mathieu Desnoyers and Paul E. McKenney
5 void rcu_init(void);
7 This must be called before any of the following functions
8 are invoked.
10 void rcu_read_lock(void);
12 Begin an RCU read-side critical section. These critical
13 sections may be nested.
15 void rcu_read_unlock(void);
17 End an RCU read-side critical section.
19 void rcu_register_thread(void);
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().
26 void rcu_unregister_thread(void);
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.
32 void synchronize_rcu(void);
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.
40 void call_rcu(struct rcu_head *head,
41 void (*func)(struct rcu_head *head));
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:
50 void func(struct rcu_head *head)
51 {
52 struct foo *p = container_of(head, struct foo, rcu);
54 free(p);
55 }
57 This RCU callback function can be registered as follows
58 given a pointer "p" to the enclosing structure:
60 call_rcu(&p->rcu, func);
62 call_rcu should be called from registered RCU read-side threads.
63 For the QSBR flavor, the caller should be online.
65 void rcu_barrier(void);
67 Wait for all call_rcu() work initiated prior to rcu_barrier() by
68 _any_ thread on the system to have completed before rcu_barrier()
69 returns. rcu_barrier() should never be called from a call_rcu()
70 thread. This function can be used, for instance, to ensure that
71 all memory reclaim involving a shared object has completed
72 before allowing dlclose() of this shared object to complete.
74 struct call_rcu_data *create_call_rcu_data(unsigned long flags,
75 int cpu_affinity);
77 Returns a handle that can be passed to the following
78 primitives. The "flags" argument can be zero, or can be
79 URCU_CALL_RCU_RT if the worker threads associated with the
80 new helper thread are to get real-time response. The argument
81 "cpu_affinity" specifies a cpu on which the call_rcu thread should
82 be affined to. It is ignored if negative.
84 void call_rcu_data_free(struct call_rcu_data *crdp);
86 Terminates a call_rcu() helper thread and frees its associated
87 data. The caller must have ensured that this thread is no longer
88 in use, for example, by passing NULL to set_thread_call_rcu_data()
89 and set_cpu_call_rcu_data() as required.
91 struct call_rcu_data *get_default_call_rcu_data(void);
93 Returns the handle for the default call_rcu() helper thread.
94 Creates it if necessary.
96 struct call_rcu_data *get_cpu_call_rcu_data(int cpu);
98 Returns the handle for the current cpu's call_rcu() helper
99 thread, or NULL if the current CPU has no helper thread
100 currently assigned. The call to this function and use of the
101 returned call_rcu_data should be protected by RCU read-side
102 lock.
104 struct call_rcu_data *get_thread_call_rcu_data(void);
106 Returns the handle for the current thread's hard-assigned
107 call_rcu() helper thread, or NULL if the current thread is
108 instead using a per-CPU or the default helper thread.
110 struct call_rcu_data *get_call_rcu_data(void);
112 Returns the handle for the current thread's call_rcu() helper
113 thread, which is either, in increasing order of preference:
114 per-thread hard-assigned helper thread, per-cpu helper thread,
115 or default helper thread. get_call_rcu_data should be called
116 from registered RCU read-side threads. For the QSBR flavor, the
117 caller should be online.
119 pthread_t get_call_rcu_thread(struct call_rcu_data *crdp);
121 Returns the helper thread's pthread identifier linked to a call
122 rcu helper thread data.
124 void set_thread_call_rcu_data(struct call_rcu_data *crdp);
126 Sets the current thread's hard-assigned call_rcu() helper to the
127 handle specified by "crdp". Note that "crdp" can be NULL to
128 disassociate this thread from its helper. Once a thread is
129 disassociated from its helper, further call_rcu() invocations
130 use the current CPU's helper if there is one and the default
131 helper otherwise.
133 int set_cpu_call_rcu_data(int cpu, struct call_rcu_data *crdp);
135 Sets the specified CPU's call_rcu() helper to the handle
136 specified by "crdp". Again, "crdp" can be NULL to disassociate
137 this CPU from its helper thread. Once a CPU has been
138 disassociated from its helper, further call_rcu() invocations
139 that would otherwise have used this CPU's helper will instead
140 use the default helper. The caller must wait for a grace-period
141 to pass between return from set_cpu_call_rcu_data() and call to
142 call_rcu_data_free() passing the previous call rcu data as
143 argument.
145 int create_all_cpu_call_rcu_data(unsigned long flags)
147 Creates a separate call_rcu() helper thread for each CPU.
148 After this primitive is invoked, the global default call_rcu()
149 helper thread will not be called.
151 The set_thread_call_rcu_data(), set_cpu_call_rcu_data(), and
152 create_all_cpu_call_rcu_data() functions may be combined to set up
153 pretty much any desired association between worker and call_rcu()
154 helper threads. If a given executable calls only call_rcu(),
155 then that executable will have only the single global default
156 call_rcu() helper thread. This will suffice in most cases.
158 void free_all_cpu_call_rcu_data(void);
160 Clean up all the per-CPU call_rcu threads. Should be paired with
161 create_all_cpu_call_rcu_data() to perform teardown. Note that
162 this function invokes synchronize_rcu() internally, so the
163 caller should be careful not to hold mutexes (or mutexes within a
164 dependency chain) that are also taken within a RCU read-side
165 critical section, or in a section where QSBR threads are online.
167 void call_rcu_after_fork_child(void);
169 Should be used as pthread_atfork() handler for programs using
170 call_rcu and performing fork() or clone() without a following
171 exec().
This page took 0.047807 seconds and 4 git commands to generate.