diff mbox series

rcu: Describe listRCU read-side guarantees

Message ID 20230822200402.159177-1-willy@infradead.org (mailing list archive)
State New, archived
Headers show
Series rcu: Describe listRCU read-side guarantees | expand

Commit Message

Matthew Wilcox Aug. 22, 2023, 8:04 p.m. UTC
More explicitly state what is, and what is not guaranteed to those
who iterate a list while protected by RCU.

Signed-off-by: Matthew Wilcox (Oracle) <willy@infradead.org>
---
 Documentation/RCU/listRCU.rst | 12 ++++++++++++
 1 file changed, 12 insertions(+)

Comments

Joel Fernandes Aug. 22, 2023, 11:28 p.m. UTC | #1
On Tue, Aug 22, 2023 at 4:04 PM Matthew Wilcox (Oracle)
<willy@infradead.org> wrote:
>
> More explicitly state what is, and what is not guaranteed to those
> who iterate a list while protected by RCU.
>
> Signed-off-by: Matthew Wilcox (Oracle) <willy@infradead.org>
> ---
>  Documentation/RCU/listRCU.rst | 12 ++++++++++++
>  1 file changed, 12 insertions(+)
>
> diff --git a/Documentation/RCU/listRCU.rst b/Documentation/RCU/listRCU.rst
> index bdc4bcc5289f..aff1394f6d93 100644
> --- a/Documentation/RCU/listRCU.rst
> +++ b/Documentation/RCU/listRCU.rst
> @@ -8,6 +8,18 @@ One of the most common uses of RCU is protecting read-mostly linked lists
>  that all of the required memory ordering is provided by the list macros.
>  This document describes several list-based RCU use cases.
>
> +When iterating a list while holding the rcu_read_lock(), writers may
> +modify the list.  The reader is guaranteed to see all of the elements
> +which were added to the list before they acquired the rcu_read_lock()
> +and are still on the list when they drop the rcu_read_unlock().
> +Elements which are added to, or removed from the list may or may not
> +be seen.  If the writer calls list_replace_rcu(), the reader may see
> +either the old element or the new element; they will not see both,
> +nor will they see neither.

Until here,
Reviewed-by: Joel Fernandes (Google) <joel@joelfernandes.org>

> +There is no equivalent of list_for_each_entry_reverse(); RCU lists
> +may only be walked forwards.
> +

Is there a need to mention that? If it changes in the future then the
docs go stale.

Thanks.
Matthew Wilcox Aug. 22, 2023, 11:54 p.m. UTC | #2
On Tue, Aug 22, 2023 at 07:28:34PM -0400, Joel Fernandes wrote:
> On Tue, Aug 22, 2023 at 4:04 PM Matthew Wilcox (Oracle)
> <willy@infradead.org> wrote:
> >
> > More explicitly state what is, and what is not guaranteed to those
> > who iterate a list while protected by RCU.
> >
> > Signed-off-by: Matthew Wilcox (Oracle) <willy@infradead.org>
> > ---
> >  Documentation/RCU/listRCU.rst | 12 ++++++++++++
> >  1 file changed, 12 insertions(+)
> >
> > diff --git a/Documentation/RCU/listRCU.rst b/Documentation/RCU/listRCU.rst
> > index bdc4bcc5289f..aff1394f6d93 100644
> > --- a/Documentation/RCU/listRCU.rst
> > +++ b/Documentation/RCU/listRCU.rst
> > @@ -8,6 +8,18 @@ One of the most common uses of RCU is protecting read-mostly linked lists
> >  that all of the required memory ordering is provided by the list macros.
> >  This document describes several list-based RCU use cases.
> >
> > +When iterating a list while holding the rcu_read_lock(), writers may
> > +modify the list.  The reader is guaranteed to see all of the elements
> > +which were added to the list before they acquired the rcu_read_lock()
> > +and are still on the list when they drop the rcu_read_unlock().
> > +Elements which are added to, or removed from the list may or may not
> > +be seen.  If the writer calls list_replace_rcu(), the reader may see
> > +either the old element or the new element; they will not see both,
> > +nor will they see neither.
> 
> Until here,
> Reviewed-by: Joel Fernandes (Google) <joel@joelfernandes.org>
> 
> > +There is no equivalent of list_for_each_entry_reverse(); RCU lists
> > +may only be walked forwards.
> > +
> 
> Is there a need to mention that? If it changes in the future then the
> docs go stale.

I don't know if there's a need to mention it.  It was something I noticed
while reviewing the code that I didn't see documented anywhere.

I don't really care; happy to send a v2 without it, or you can just
apply the first paragraph.
Joel Fernandes Aug. 23, 2023, 1:24 p.m. UTC | #3
On Tue, Aug 22, 2023 at 7:54 PM Matthew Wilcox <willy@infradead.org> wrote:
>
> On Tue, Aug 22, 2023 at 07:28:34PM -0400, Joel Fernandes wrote:
> > On Tue, Aug 22, 2023 at 4:04 PM Matthew Wilcox (Oracle)
> > <willy@infradead.org> wrote:
> > >
> > > More explicitly state what is, and what is not guaranteed to those
> > > who iterate a list while protected by RCU.
> > >
> > > Signed-off-by: Matthew Wilcox (Oracle) <willy@infradead.org>
> > > ---
> > >  Documentation/RCU/listRCU.rst | 12 ++++++++++++
> > >  1 file changed, 12 insertions(+)
> > >
> > > diff --git a/Documentation/RCU/listRCU.rst b/Documentation/RCU/listRCU.rst
> > > index bdc4bcc5289f..aff1394f6d93 100644
> > > --- a/Documentation/RCU/listRCU.rst
> > > +++ b/Documentation/RCU/listRCU.rst
> > > @@ -8,6 +8,18 @@ One of the most common uses of RCU is protecting read-mostly linked lists
> > >  that all of the required memory ordering is provided by the list macros.
> > >  This document describes several list-based RCU use cases.
> > >
> > > +When iterating a list while holding the rcu_read_lock(), writers may
> > > +modify the list.  The reader is guaranteed to see all of the elements
> > > +which were added to the list before they acquired the rcu_read_lock()
> > > +and are still on the list when they drop the rcu_read_unlock().
> > > +Elements which are added to, or removed from the list may or may not
> > > +be seen.  If the writer calls list_replace_rcu(), the reader may see
> > > +either the old element or the new element; they will not see both,
> > > +nor will they see neither.
> >
> > Until here,
> > Reviewed-by: Joel Fernandes (Google) <joel@joelfernandes.org>
> >
> > > +There is no equivalent of list_for_each_entry_reverse(); RCU lists
> > > +may only be walked forwards.
> > > +
> >
> > Is there a need to mention that? If it changes in the future then the
> > docs go stale.
>
> I don't know if there's a need to mention it.  It was something I noticed
> while reviewing the code that I didn't see documented anywhere.
>
> I don't really care; happy to send a v2 without it, or you can just
> apply the first paragraph.

That sounds good to me, Paul do you want to apply it with my Review
tag and without the last para?

thanks,

 - Joel
Paul E. McKenney Aug. 23, 2023, 9:22 p.m. UTC | #4
On Wed, Aug 23, 2023 at 09:24:21AM -0400, Joel Fernandes wrote:
> On Tue, Aug 22, 2023 at 7:54 PM Matthew Wilcox <willy@infradead.org> wrote:
> >
> > On Tue, Aug 22, 2023 at 07:28:34PM -0400, Joel Fernandes wrote:
> > > On Tue, Aug 22, 2023 at 4:04 PM Matthew Wilcox (Oracle)
> > > <willy@infradead.org> wrote:
> > > >
> > > > More explicitly state what is, and what is not guaranteed to those
> > > > who iterate a list while protected by RCU.
> > > >
> > > > Signed-off-by: Matthew Wilcox (Oracle) <willy@infradead.org>
> > > > ---
> > > >  Documentation/RCU/listRCU.rst | 12 ++++++++++++
> > > >  1 file changed, 12 insertions(+)
> > > >
> > > > diff --git a/Documentation/RCU/listRCU.rst b/Documentation/RCU/listRCU.rst
> > > > index bdc4bcc5289f..aff1394f6d93 100644
> > > > --- a/Documentation/RCU/listRCU.rst
> > > > +++ b/Documentation/RCU/listRCU.rst
> > > > @@ -8,6 +8,18 @@ One of the most common uses of RCU is protecting read-mostly linked lists
> > > >  that all of the required memory ordering is provided by the list macros.
> > > >  This document describes several list-based RCU use cases.
> > > >
> > > > +When iterating a list while holding the rcu_read_lock(), writers may
> > > > +modify the list.  The reader is guaranteed to see all of the elements
> > > > +which were added to the list before they acquired the rcu_read_lock()
> > > > +and are still on the list when they drop the rcu_read_unlock().
> > > > +Elements which are added to, or removed from the list may or may not
> > > > +be seen.  If the writer calls list_replace_rcu(), the reader may see
> > > > +either the old element or the new element; they will not see both,
> > > > +nor will they see neither.
> > >
> > > Until here,
> > > Reviewed-by: Joel Fernandes (Google) <joel@joelfernandes.org>
> > >
> > > > +There is no equivalent of list_for_each_entry_reverse(); RCU lists
> > > > +may only be walked forwards.
> > > > +
> > >
> > > Is there a need to mention that? If it changes in the future then the
> > > docs go stale.
> >
> > I don't know if there's a need to mention it.  It was something I noticed
> > while reviewing the code that I didn't see documented anywhere.
> >
> > I don't really care; happy to send a v2 without it, or you can just
> > apply the first paragraph.
> 
> That sounds good to me, Paul do you want to apply it with my Review
> tag and without the last para?

Here you two go, and thank you both!

							Thanx, Paul

------------------------------------------------------------------------

commit 06f9695d1b62163036581722f29fef2d93aa7909
Author: Matthew Wilcox (Oracle) <willy@infradead.org>
Date:   Tue Aug 22 21:04:02 2023 +0100

    rcu: Describe listRCU read-side guarantees
    
    More explicitly state what is, and what is not guaranteed to those
    who iterate a list while protected by RCU.
    
    [ paulmck: Apply Joel Fernandes feedback. ]
    
    Signed-off-by: Matthew Wilcox (Oracle) <willy@infradead.org>
    Reviewed-by: Joel Fernandes (Google) <joel@joelfernandes.org>
    Signed-off-by: Paul E. McKenney <paulmck@kernel.org>

diff --git a/Documentation/RCU/listRCU.rst b/Documentation/RCU/listRCU.rst
index bdc4bcc5289f..ed5c9d8c9afe 100644
--- a/Documentation/RCU/listRCU.rst
+++ b/Documentation/RCU/listRCU.rst
@@ -8,6 +8,15 @@ One of the most common uses of RCU is protecting read-mostly linked lists
 that all of the required memory ordering is provided by the list macros.
 This document describes several list-based RCU use cases.
 
+When iterating a list while holding the rcu_read_lock(), writers may
+modify the list.  The reader is guaranteed to see all of the elements
+which were added to the list before they acquired the rcu_read_lock()
+and are still on the list when they drop the rcu_read_unlock().
+Elements which are added to, or removed from the list may or may not
+be seen.  If the writer calls list_replace_rcu(), the reader may see
+either the old element or the new element; they will not see both,
+nor will they see neither.
+
 
 Example 1: Read-mostly list: Deferred Destruction
 -------------------------------------------------
diff mbox series

Patch

diff --git a/Documentation/RCU/listRCU.rst b/Documentation/RCU/listRCU.rst
index bdc4bcc5289f..aff1394f6d93 100644
--- a/Documentation/RCU/listRCU.rst
+++ b/Documentation/RCU/listRCU.rst
@@ -8,6 +8,18 @@  One of the most common uses of RCU is protecting read-mostly linked lists
 that all of the required memory ordering is provided by the list macros.
 This document describes several list-based RCU use cases.
 
+When iterating a list while holding the rcu_read_lock(), writers may
+modify the list.  The reader is guaranteed to see all of the elements
+which were added to the list before they acquired the rcu_read_lock()
+and are still on the list when they drop the rcu_read_unlock().
+Elements which are added to, or removed from the list may or may not
+be seen.  If the writer calls list_replace_rcu(), the reader may see
+either the old element or the new element; they will not see both,
+nor will they see neither.
+
+There is no equivalent of list_for_each_entry_reverse(); RCU lists
+may only be walked forwards.
+
 
 Example 1: Read-mostly list: Deferred Destruction
 -------------------------------------------------