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