doc/rcu-api.txt

   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         call_rcu should be called from registered RCU read-side threads.
  63         For the QSBR flavor, the caller should be online.
  64
  65 void rcu_barrier(void);
  66
  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.
  73
  74 struct call_rcu_data *create_call_rcu_data(unsigned long flags,
  75                                            int cpu_affinity);
  76
  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.
  83
  84 void call_rcu_data_free(struct call_rcu_data *crdp);
  85
  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.
  90
  91 struct call_rcu_data *get_default_call_rcu_data(void);
  92
  93         Returns the handle for the default call_rcu() helper thread.
  94         Creates it if necessary.
  95
  96 struct call_rcu_data *get_cpu_call_rcu_data(int cpu);
  97
  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.
 103
 104 struct call_rcu_data *get_thread_call_rcu_data(void);
 105
 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.
 109
 110 struct call_rcu_data *get_call_rcu_data(void);
 111
 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.
 118
 119 pthread_t get_call_rcu_thread(struct call_rcu_data *crdp);
 120
 121         Returns the helper thread's pthread identifier linked to a call
 122         rcu helper thread data.
 123
 124 void set_thread_call_rcu_data(struct call_rcu_data *crdp);
 125
 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.
 132
 133 int set_cpu_call_rcu_data(int cpu, struct call_rcu_data *crdp);
 134
 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.
 144
 145 int create_all_cpu_call_rcu_data(unsigned long flags)
 146
 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.
 150
 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.
 157
 158 void free_all_cpu_call_rcu_data(void);
 159
 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.
 166
 167 void call_rcu_after_fork_child(void);
 168
 169         Should be used as pthread_atfork() handler for programs using
 170         call_rcu and performing fork() or clone() without a following
 171         exec().