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

[Paul E. McKenney]

On Wed, Jun 01, 2011 at 10:37:41AM -0400, Mathieu Desnoyers wrote:
> * 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 ?

Sounds good, I will submit a patch to this effect.

							Thanx, Paul

> Mathieu
> 
> > 
> > 							Thanx, Paul
> > 
> 
> -- 
> Mathieu Desnoyers
> Operating System Efficiency R&D Consultant
> EfficiOS Inc.
> http://www.efficios.com
> 
> _______________________________________________
> rp mailing list
> rp at svcs.cs.pdx.edu
> http://svcs.cs.pdx.edu/mailman/listinfo/rp