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

[compudj@krystal.dyndns.org (Mathieu Desnoyers)]

* Paul E. McKenney (paulmck at linux.vnet.ibm.com) wrote:
> 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?

We might as well start simple first with API.txt, and then switch to
docbook when we see the need for it ?

Mathieu

> 
> 							Thanx, Paul
> 

-- 
Mathieu Desnoyers
Operating System Efficiency R&D Consultant
EfficiOS Inc.
http://www.efficios.com