On Tue, Aug 22, 2023 at 4:04 PM Matthew Wilcox (Oracle) <willy@xxxxxxxxxxxxx> 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@xxxxxxxxxxxxx> > --- > 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@xxxxxxxxxxxxxxxxx> > +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.
