| 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 | |
| 19 | void 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 | |
| 26 | void 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 | |
| 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 | |
| 62 | struct call_rcu_data *create_call_rcu_data(unsigned long flags, |
| 63 | int cpu_affinity); |
| 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 |
| 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. |
| 71 | |
| 72 | struct call_rcu_data *get_default_call_rcu_data(void); |
| 73 | |
| 74 | Returns the handle of the default call_rcu() helper thread. |
| 75 | |
| 76 | struct 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 | |
| 81 | struct 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 | |
| 87 | void 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 | |
| 96 | int 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 | |
| 105 | int 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 | |
| 118 | void 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. |