[ltt-dev] [PATCH userspace-rcu] document the call_rcu() family of primitives

[Paul E. McKenney]

Just in case documentation is desired.  ;-)

							Thanx, Paul

------------------------------------------------------------------------

Document the new call_rcu() primitives.

Signed-off-by: Paul E. McKenney <paulmck at linux.vnet.ibm.com>

diff --git a/README b/README
index 7d97f19..0e5ad47 100644
--- a/README
+++ b/README
@@ -139,6 +139,79 @@ Usage of liburcu-defer
 	* Its API is currently experimental. It may change in future library
 	  releases.
 
+Usage of urcu-call-rcu
+
+	* Follow instructions for either liburcu, liburcu-qsbr,
+	  liburcu-mb, liburcu-signal, or liburcu-bp above.
+	  The urcu-call-rcu functionality is provided for each of
+	  these library modules.
+	* Provides the call_rcu() primitive to enqueue delayed callbacks
+	  in a manner similar to defer_rcu(), but without ever delaying
+	  for a grace period.  On the other hand, call_rcu()'s best-case
+	  overhead is not quite as good as that of defer_rcu().
+	* Provides the following primitive to create call_rcu() helper
+	  threads:
+
+	  struct call_rcu_data *create_call_rcu_data(unsigned long flags);
+
+	  This returns a handle that can be passed to the following
+	  primitives.  The "flags" argument can be zero, or can be
+	  URCU_CALL_RCU_RT if the worker threads associated with the
+	  new helper thread are to get real-time response.
+	* Provides the following primitive to return the handle of
+	  the default call_rcu() helper thread:
+
+	  struct call_rcu_data *get_default_call_rcu_data(void);
+
+	* Provides the following primitive to return the handle of the
+	  current thread's call_rcu() helper thread (which might well
+	  be the default helper thread):
+
+	  struct call_rcu_data *get_call_rcu_data(void);
+
+	* Provides the following primitive to return the handle for the
+	  current thread's hard-assigned call_rcu() helper thread:
+
+	  struct call_rcu_data *get_thread_call_rcu_data(void);
+
+	  This returns NULL if the current thread is instead using a
+	  per-CPU or the default helper thread.
+	* Provides the following primitive to set the current thread's 
+	  hard-assigned call_rcu() helper to the specified handle:
+
+	  void set_thread_call_rcu_data(struct call_rcu_data *crdp);
+
+	  Note that "crdp" can be NULL to disassociate this thread from
+	  its helper.
+	* Provides the following primitive to set the specified CPU's
+	  call_rcu() helper to the specified handle:
+
+	  int set_cpu_call_rcu_data(int cpu, struct call_rcu_data *crdp);
+
+	  Note that "crdp" can be NULL to disassociate this CPU from
+	  its helper.
+	* Provides the following primitive to create a separate call_rcu()
+	  helper thread for each CPU:
+
+	  int create_all_cpu_call_rcu_data(unsigned long flags)
+
+	  After this primitive is invoked, the global default call_rcu()
+	  helper thread will not be called.
+	* Provides the following primitive to terminate a call_rcu() helper
+	  thread and free its associated data:
+
+	  void call_rcu_data_free(struct call_rcu_data *crdp)
+
+	  The caller must have ensured that this thread is no longer in
+	  use, for example, by passing NULL to set_thread_call_rcu_data()
+	  or set_cpu_call_rcu_data() as required.
+
+	These primitives may be combined to set up pretty much any desired
+	association between worker and call_rcu() helper threads.  If
+	a given executable calls only call_rcu(), then that executable
+	will have only the single global default call_rcu() helper
+	thread.  This will suffice in most cases.
+
 Being careful with signals
 
 	The liburcu library uses signals internally. The signal handler is