Re: [PATCH 2/2] Doc: Fix wrong API example usage of call_rcu().

["Paul E. McKenney" <paulmck@linux.vnet.ibm.com>]

On Fri, Mar 06, 2009 at 09:49:59PM -0800, Paul E. McKenney wrote:
> On Fri, Mar 06, 2009 at 02:27:38PM +0100, Jesper Dangaard Brouer wrote:
> > At some point the API of call_rcu() changed from three parameters
> > to two parameters, correct the documentation.
> > 
> > One confusing thing in RCU/listRCU.txt, which is NOT fixed in this patch,
> > is that no reason or explaination is given for using call_rcu() instead of
> > the normal synchronize_rcu() call.
> 
> Good catch!!!  Indeed, call_rcu() did take three arguments at one time,
> like back in 2.5 days...
> 
> On the use of call_rcu() vs. synchronize_rcu(), the two possible reasons
> called out in question 8 in Documentation/RCU/checklist.txt are:
> 
> 1.	Update performance is important.
> 
> 2.	Updaters cannot block.

And an important special case of #2 is when the update is being carried
out within an RCU read-side critical section, FWIW.

							Thanx, Paul

> I would welcome a patch to this file discussing this.
> 
> Reviewed-by: Paul E. McKenney <paulmck@linux.vnet.ibm.com>
> 
> > Signed-off-by: Jesper Dangaard Brouer <hawk@comx.dk>
> > ---
> > 
> >  Documentation/RCU/listRCU.txt |    6 +++---
> >  1 files changed, 3 insertions(+), 3 deletions(-)
> > 
> > diff --git a/Documentation/RCU/listRCU.txt b/Documentation/RCU/listRCU.txt
> > index 1fd1753..4349c14 100644
> > --- a/Documentation/RCU/listRCU.txt
> > +++ b/Documentation/RCU/listRCU.txt
> > @@ -118,7 +118,7 @@ Following are the RCU equivalents for these two functions:
> >  		list_for_each_entry(e, list, list) {
> >  			if (!audit_compare_rule(rule, &e->rule)) {
> >  				list_del_rcu(&e->list);
> > -				call_rcu(&e->rcu, audit_free_rule, e);
> > +				call_rcu(&e->rcu, audit_free_rule);
> >  				return 0;
> >  			}
> >  		}
> > @@ -206,7 +206,7 @@ RCU ("read-copy update") its name.  The RCU code is as follows:
> >  				ne->rule.action = newaction;
> >  				ne->rule.file_count = newfield_count;
> >  				list_replace_rcu(e, ne);
> > -				call_rcu(&e->rcu, audit_free_rule, e);
> > +				call_rcu(&e->rcu, audit_free_rule);
> >  				return 0;
> >  			}
> >  		}
> > @@ -283,7 +283,7 @@ flag under the spinlock as follows:
> >  				list_del_rcu(&e->list);
> >  				e->deleted = 1;
> >  				spin_unlock(&e->lock);
> > -				call_rcu(&e->rcu, audit_free_rule, e);
> > +				call_rcu(&e->rcu, audit_free_rule);
> >  				return 0;
> >  			}
> >  		}
> >