[Patch v2] doc/RCU/listRCU: refine example code for eliminating stale data

[Patch v2] doc/RCU/listRCU: refine example code for eliminating stale data

[Wei Yang]

This patch adjust the example code with following two purpose:

  * reduce the confusion on not releasing e->lock
  * emphasize e is valid and not stale with e->lock held

Signed-off-by: Wei Yang <richard.weiyang@gmail.com>
CC: Boqun Feng <boqun.feng@gmail.com>
CC: Alan Huang <mmpgouride@gmail.com>

---
v2:
  * add the missing parameter *key
  * make function return struct audit_entry
---
 Documentation/RCU/listRCU.rst | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/Documentation/RCU/listRCU.rst b/Documentation/RCU/listRCU.rst
index ed5c9d8c9afe..d8bb98623c12 100644
--- a/Documentation/RCU/listRCU.rst
+++ b/Documentation/RCU/listRCU.rst
@@ -334,7 +334,7 @@ If the system-call audit module were to ever need to reject stale data, one way
 to accomplish this would be to add a ``deleted`` flag and a ``lock`` spinlock to the
 ``audit_entry`` structure, and modify audit_filter_task() as follows::
 
-	static enum audit_state audit_filter_task(struct task_struct *tsk)
+	static struct audit_entry *audit_filter_task(struct task_struct *tsk, char **key)
 	{
 		struct audit_entry *e;
 		enum audit_state   state;
@@ -346,16 +346,18 @@ to accomplish this would be to add a ``deleted`` flag and a ``lock`` spinlock to
 				if (e->deleted) {
 					spin_unlock(&e->lock);
 					rcu_read_unlock();
-					return AUDIT_BUILD_CONTEXT;
+					return NULL;
 				}
 				rcu_read_unlock();
 				if (state == AUDIT_STATE_RECORD)
 					*key = kstrdup(e->rule.filterkey, GFP_ATOMIC);
-				return state;
+				/* As long as e->lock is held, e is valid and
+				 * its value is not stale */
+				return e;
 			}
 		}
 		rcu_read_unlock();
-		return AUDIT_BUILD_CONTEXT;
+		return NULL;
 	}
 
 The ``audit_del_rule()`` function would need to set the ``deleted`` flag under the
-- 
2.34.1

Re: [Patch v2] doc/RCU/listRCU: refine example code for eliminating stale data

[Boqun Feng]

On Tue, Feb 18, 2025 at 12:50:47AM +0000, Wei Yang wrote:
> This patch adjust the example code with following two purpose:
> 
>   * reduce the confusion on not releasing e->lock
>   * emphasize e is valid and not stale with e->lock held
> 
> Signed-off-by: Wei Yang <richard.weiyang@gmail.com>
> CC: Boqun Feng <boqun.feng@gmail.com>
> CC: Alan Huang <mmpgouride@gmail.com>
> 

Alan, could you take a look and if all looks reasonable to you, maybe a
Reviewed-by or Acked-by? Thanks!

Regards,
Boqun

> ---
> v2:
>   * add the missing parameter *key
>   * make function return struct audit_entry
> ---
>  Documentation/RCU/listRCU.rst | 10 ++++++----
>  1 file changed, 6 insertions(+), 4 deletions(-)
> 
> diff --git a/Documentation/RCU/listRCU.rst b/Documentation/RCU/listRCU.rst
> index ed5c9d8c9afe..d8bb98623c12 100644
> --- a/Documentation/RCU/listRCU.rst
> +++ b/Documentation/RCU/listRCU.rst
> @@ -334,7 +334,7 @@ If the system-call audit module were to ever need to reject stale data, one way
>  to accomplish this would be to add a ``deleted`` flag and a ``lock`` spinlock to the
>  ``audit_entry`` structure, and modify audit_filter_task() as follows::
>  
> -	static enum audit_state audit_filter_task(struct task_struct *tsk)
> +	static struct audit_entry *audit_filter_task(struct task_struct *tsk, char **key)
>  	{
>  		struct audit_entry *e;
>  		enum audit_state   state;
> @@ -346,16 +346,18 @@ to accomplish this would be to add a ``deleted`` flag and a ``lock`` spinlock to
>  				if (e->deleted) {
>  					spin_unlock(&e->lock);
>  					rcu_read_unlock();
> -					return AUDIT_BUILD_CONTEXT;
> +					return NULL;
>  				}
>  				rcu_read_unlock();
>  				if (state == AUDIT_STATE_RECORD)
>  					*key = kstrdup(e->rule.filterkey, GFP_ATOMIC);
> -				return state;
> +				/* As long as e->lock is held, e is valid and
> +				 * its value is not stale */
> +				return e;
>  			}
>  		}
>  		rcu_read_unlock();
> -		return AUDIT_BUILD_CONTEXT;
> +		return NULL;
>  	}
>  
>  The ``audit_del_rule()`` function would need to set the ``deleted`` flag under the
> -- 
> 2.34.1
> 
> 

Re: [Patch v2] doc/RCU/listRCU: refine example code for eliminating stale data

[Alan Huang]

On Feb 18, 2025, at 08:50, Wei Yang <richard.weiyang@gmail.com> wrote:
> 
> This patch adjust the example code with following two purpose:
> 
>  * reduce the confusion on not releasing e->lock
>  * emphasize e is valid and not stale with e->lock held
> 
> Signed-off-by: Wei Yang <richard.weiyang@gmail.com>
> CC: Boqun Feng <boqun.feng@gmail.com>
> CC: Alan Huang <mmpgouride@gmail.com>
> 
> ---
> v2:
>  * add the missing parameter *key
>  * make function return struct audit_entry
> ---
> Documentation/RCU/listRCU.rst | 10 ++++++----
> 1 file changed, 6 insertions(+), 4 deletions(-)
> 
> diff --git a/Documentation/RCU/listRCU.rst b/Documentation/RCU/listRCU.rst
> index ed5c9d8c9afe..d8bb98623c12 100644
> --- a/Documentation/RCU/listRCU.rst
> +++ b/Documentation/RCU/listRCU.rst
> @@ -334,7 +334,7 @@ If the system-call audit module were to ever need to reject stale data, one way
> to accomplish this would be to add a ``deleted`` flag and a ``lock`` spinlock to the
> ``audit_entry`` structure, and modify audit_filter_task() as follows::
> 
> - static enum audit_state audit_filter_task(struct task_struct *tsk)
> + static struct audit_entry *audit_filter_task(struct task_struct *tsk, char **key)
> {
> struct audit_entry *e;
> enum audit_state   state;
> @@ -346,16 +346,18 @@ to accomplish this would be to add a ``deleted`` flag and a ``lock`` spinlock to
> if (e->deleted) {
> spin_unlock(&e->lock);
> rcu_read_unlock();
> - return AUDIT_BUILD_CONTEXT;
> + return NULL;
> }
> rcu_read_unlock();
> if (state == AUDIT_STATE_RECORD)
> *key = kstrdup(e->rule.filterkey, GFP_ATOMIC);
> - return state;
> + /* As long as e->lock is held, e is valid and
> + * its value is not stale */
> + return e;
> }
> }
> rcu_read_unlock();
> - return AUDIT_BUILD_CONTEXT;
> + return NULL;
> }
> 
> The ``audit_del_rule()`` function would need to set the ``deleted`` flag under the
> -- 
> 2.34.1
> 

I think it’s good enough to illustrate the intention here:

Reviewed-by: Alan Huang <mmpgouride@gmail.com>

Boqun, there is an unreviewed doc patch[1] that fixes the section

 “Using RCU hlist_nulls to protect list and objects”

[1] https://lore.kernel.org/rcu/20240326124431.77430-1-mmpgouride@gmail.com/

: )

Re: [Patch v2] doc/RCU/listRCU: refine example code for eliminating stale data

[Boqun Feng]

On Thu, Feb 20, 2025 at 12:40:20AM +0800, Alan Huang wrote:
> On Feb 18, 2025, at 08:50, Wei Yang <richard.weiyang@gmail.com> wrote:
> > 
> > This patch adjust the example code with following two purpose:
> > 
> >  * reduce the confusion on not releasing e->lock
> >  * emphasize e is valid and not stale with e->lock held
> > 
> > Signed-off-by: Wei Yang <richard.weiyang@gmail.com>
> > CC: Boqun Feng <boqun.feng@gmail.com>
> > CC: Alan Huang <mmpgouride@gmail.com>
> > 
> > ---
> > v2:
> >  * add the missing parameter *key
> >  * make function return struct audit_entry
> > ---
> > Documentation/RCU/listRCU.rst | 10 ++++++----
> > 1 file changed, 6 insertions(+), 4 deletions(-)
> > 
> > diff --git a/Documentation/RCU/listRCU.rst b/Documentation/RCU/listRCU.rst
> > index ed5c9d8c9afe..d8bb98623c12 100644
> > --- a/Documentation/RCU/listRCU.rst
> > +++ b/Documentation/RCU/listRCU.rst
> > @@ -334,7 +334,7 @@ If the system-call audit module were to ever need to reject stale data, one way
> > to accomplish this would be to add a ``deleted`` flag and a ``lock`` spinlock to the
> > ``audit_entry`` structure, and modify audit_filter_task() as follows::
> > 
> > - static enum audit_state audit_filter_task(struct task_struct *tsk)
> > + static struct audit_entry *audit_filter_task(struct task_struct *tsk, char **key)
> > {
> > struct audit_entry *e;
> > enum audit_state   state;
> > @@ -346,16 +346,18 @@ to accomplish this would be to add a ``deleted`` flag and a ``lock`` spinlock to
> > if (e->deleted) {
> > spin_unlock(&e->lock);
> > rcu_read_unlock();
> > - return AUDIT_BUILD_CONTEXT;
> > + return NULL;
> > }
> > rcu_read_unlock();
> > if (state == AUDIT_STATE_RECORD)
> > *key = kstrdup(e->rule.filterkey, GFP_ATOMIC);
> > - return state;
> > + /* As long as e->lock is held, e is valid and
> > + * its value is not stale */
> > + return e;
> > }
> > }
> > rcu_read_unlock();
> > - return AUDIT_BUILD_CONTEXT;
> > + return NULL;
> > }
> > 
> > The ``audit_del_rule()`` function would need to set the ``deleted`` flag under the
> > -- 
> > 2.34.1
> > 
> 
> I think it’s good enough to illustrate the intention here:
> 
> Reviewed-by: Alan Huang <mmpgouride@gmail.com>
> 

Queued for further tests and reviews, thanks you both!

> Boqun, there is an unreviewed doc patch[1] that fixes the section
> 
>  “Using RCU hlist_nulls to protect list and objects”
> 
> [1] https://lore.kernel.org/rcu/20240326124431.77430-1-mmpgouride@gmail.com/
> 
> : )
> 

Will take a look later.

Regards,
Boqun

> 
> 
>