rcutorture: make goflag volatile
[urcu.git] / API.txt
CommitLineData
26ba798a
PM
1Userspace RCU API
2by Mathieu Desnoyers and Paul E. McKenney
3
4
5void rcu_init(void);
6
7 This must be called before any of the following functions
8 are invoked.
9
10void rcu_read_lock(void);
11
12 Begin an RCU read-side critical section. These critical
13 sections may be nested.
14
15void rcu_read_unlock(void);
16
17 End an RCU read-side critical section.
18
19void rcu_register_thread(void)
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
26void rcu_unregister_thread(void)
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
32void 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
40void 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
c1d2c60b
MD
62struct call_rcu_data *create_call_rcu_data(unsigned long flags,
63 int cpu_affinity);
26ba798a
PM
64
65 Returns a handle that can be passed to the following
66 primitives. The "flags" argument can be zero, or can be
67 URCU_CALL_RCU_RT if the worker threads associated with the
c1d2c60b
MD
68 new helper thread are to get real-time response. The argument
69 "cpu_affinity" specifies a cpu on which the call_rcu thread should
70 be affined to. It is ignored if negative.
26ba798a
PM
71
72struct call_rcu_data *get_default_call_rcu_data(void);
73
74 Returns the handle of the default call_rcu() helper thread.
75
76struct call_rcu_data *get_call_rcu_data(void);
77
78 Returns the handle of the current thread's call_rcu() helper
79 thread, which might well be the default helper thread.
80
81struct call_rcu_data *get_thread_call_rcu_data(void);
82
83 Returns the handle for the current thread's hard-assigned
84 call_rcu() helper thread, or NULL if the current thread is
85 instead using a per-CPU or the default helper thread.
86
87void set_thread_call_rcu_data(struct call_rcu_data *crdp);
88
89 Sets the current thread's hard-assigned call_rcu() helper to the
90 handle specified by "crdp". Note that "crdp" can be NULL to
91 disassociate this thread from its helper. Once a thread is
92 disassociated from its helper, further call_rcu() invocations
93 use the current CPU's helper if there is one and the default
94 helper otherwise.
95
96int set_cpu_call_rcu_data(int cpu, struct call_rcu_data *crdp);
97
98 Sets the specified CPU's call_rcu() helper to the handle
99 specified by "crdp". Again, "crdp" can be NULL to disassociate
100 this CPU from its helper thread. Once a CPU has been
101 disassociated from its helper, further call_rcu() invocations
102 that would otherwise have used this CPU's helper will instead
103 use the default helper.
104
105int create_all_cpu_call_rcu_data(unsigned long flags)
106
107 Creates a separate call_rcu() helper thread for each CPU.
108 After this primitive is invoked, the global default call_rcu()
109 helper thread will not be called.
110
111 The set_thread_call_rcu_data(), set_cpu_call_rcu_data(), and
112 create_all_cpu_call_rcu_data() functions may be combined to set up
113 pretty much any desired association between worker and call_rcu()
114 helper threads. If a given executable calls only call_rcu(),
115 then that executable will have only the single global default
116 call_rcu() helper thread. This will suffice in most cases.
117
118void call_rcu_data_free(struct call_rcu_data *crdp)
119
120 Terminates a call_rcu() helper thread and frees its associated
121 data. The caller must have ensured that this thread is no longer
122 in use, for example, by passing NULL to set_thread_call_rcu_data()
123 and set_cpu_call_rcu_data() as required.
This page took 0.02757 seconds and 4 git commands to generate.