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

[Paul E. McKenney]

On Tue, May 31, 2011 at 05:51:53PM -0400, Mathieu Desnoyers wrote:
> * Paul E. McKenney (paulmck at linux.vnet.ibm.com) wrote:
> > 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
> > +
> [...]
> > +
> > +	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.
> 
> Hi Paul,
> 
> It might be good to keep the information at a level appropriate for
> people wanting to familiarize themself with the library. Most
> importantly, I don't want people to run away screaming when they see the
> full set of options when all they really need is to simply do:
> 
> #include <urcu-call-rcu.h>
> 
> add struct rcu_head structures and pass them to
> 
>   call_rcu(...);
> 
> into their code along with a callback.
> 
> We could lift out the rest of the discussion about the various detailed
> tweaks into a separate document.
> 
> How does that sound ?

Sounds reasonable.

Where should the separate document go?  One approach is docbook headers.
Another is something like an API.txt.  Thoughts?

							Thanx, Paul