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

From: "Paul E. McKenney" <[email-masked]>
Date: Fri, 6 Mar 2009 21:49:59 -0800

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.

I would welcome a patch to this file discussing this.

Reviewed-by: Paul E. McKenney <[email-masked]>

> Signed-off-by: Jesper Dangaard Brouer <[email-masked]>
> ---
> 
>  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;
>  			}
>  		}
>