On Mon, Jan 10, 2022 at 07:55:53AM +0900, Akira Yokosawa wrote:
> On Sun, 9 Jan 2022 10:30:23 -0800, Paul E. McKenney wrote:
> > On Sun, Jan 09, 2022 at 10:26:24AM -0800, Paul E. McKenney wrote:
> >> On Sun, Jan 09, 2022 at 10:35:28AM +0900, Akira Yokosawa wrote:
> >>> Hi Paul,
> >>>
> >>> Here are a few comments occurred to me while reading Section
> >>> 9.5.1.2.
> >>>
> >>> o Section title reads "Core RCU API", whereas Table 9.1's
> >>> caption reads "RCU Core API". They look somewhat
> >>> inconsistent. Is the difference intentional?
> >>
> >> Not intentional. I guess I was just taking thinking forwards and
> >> backwards to an extreme or something. Good catch, fixed with attribution,
> >> thank you! (I chose "Core RCU API" pretty much arbitrarily.)
> >>
> >>> o In the introduction of rcu_dereference(), the term of
> >>> "an RCU-protected pointer" is used first time throughout
> >>> this book. It is also used in the new Table 9.1.
> >>>
> >>> I think it is pretty obvious for you what it means, but a
> >>> first-time reader might wonder, "What does protecting a
> >>> pointer mean?"
> >>>
> >>> A short answer would be something like:
> >>>
> >>> What is protected by an RCU read-side critical section is
> >>> not the pointer itself, but an instance of a pointed-to
> >>> data structure on memory.
> >>>
> >>> You can expand as you'd like.
> >>
> >> How about as shown below?
> >>
> >> Thanx, Paul
> >>
> >> ------------------------------------------------------------------------
> >>
> >> commit 426fa71dff706185a64087988ee7a7a25d4c7bf1
> >> Author: Paul E. McKenney <paulmck@xxxxxxxxxx>
> >> Date: Sun Jan 9 10:24:47 2022 -0800
> >>
> >> defer/rcuintro: Add QQ on "RCU-protected pointer" definition
> >>
> >> Also add both "RCU-protected pointer" and "RCU-protected data" to
> >> the glossary.
> >>
> >> Reported-by: Akira Yokosawa <akiyks@xxxxxxxxx>
> >> Signed-off-by: Paul E. McKenney <paulmck@xxxxxxxxxx>
> >>
> >> diff --git a/defer/rcuintro.tex b/defer/rcuintro.tex
> >> index 4dfbcfda..dc464742 100644
> >> --- a/defer/rcuintro.tex
> >> +++ b/defer/rcuintro.tex
> >> @@ -210,6 +210,26 @@ that \co{rcu_dereference()} must prevent the compiler and (in
> >> one case) the CPU from reordering its load with later memory operations
> >> that dereference this pointer.
> >>
> >> +\QuickQuiz{
> >> + What is an RCU-protected pointer?
> >> +}\QuickQuizAnswer{
> >> + A pointer to RCU-protected data.
> >> + RCU-protected data is in turn a block of dynamically allocated
> >> + memory whose freeing will be deferred such that an RCU grace
> >> + period will elapse between the time that there were no longer
> >> + any RCU-reader-accessible pointers to that block and the time
> >> + that that block is freed.
> >> + This ensures that no RCU readers will have access to that block at
> >> + the time that it is freed.
> >> +
> >> + RCU-protected pointers must be handled carefully.
> >> + For example, any reader that intends to dereference an
> >> + RCU-protected pointer must use \co{rcu_dereference()} (or
> >> + stronger) to load that pointer.
> >> + In addition, any updater must use \co{rcu_assign_pointer()}
> >> + (or stronger) to store to that pointer.
> >> +}\QuickQuizEnd
> >> +
> >> The other three members of the core APIs are used by updaters.
> >> The \apik{synchronize_rcu()} function implements the ``wait for readers''
> >> operation from \cref{fig:defer:Deletion With Concurrent Readers}.
> >> diff --git a/glossary.tex b/glossary.tex
> >> index 31c09232..efba1089 100644
> >> --- a/glossary.tex
> >> +++ b/glossary.tex
> >> @@ -431,6 +431,20 @@
> >> outside of an RCU read-side critical section.
> >> Any interval of time during which all threads pass through at
> >> least one quiescent state each is termed a ``grace period''.
> >> +\item[\IX{RCU-Protected Data}:]
> >
> > Except that this results in an index entry of "Rcu-protected data".
> > I changed to this:
> >
> > +\item[\IX{{RCUa}-Protected Data}:]>
> > This suppressed addition of this term to the index, which isn't optimal,
> > but it better than "Rcu-protected data".
> >
> >> + A block of dynamically allocated memory whose freeing will be
> >> + deferred such that an RCU grace period will elapse between the
> >> + time that there were no longer any RCU-reader-accessible pointers
> >> + to that block and the time that that block is freed.
> >> + This ensures that no RCU readers will have access to that block at
> >> + the time that it is freed.
> >> +\item[\IX{RCU-Protected Pointer}:]
> >
> > And of course the same here.
> >
> > Is there a better way?
>
> When you need to keep upper-case letters in the index, \IXr{} is
> for you. Its definition in perfbook-lt.tex reads:
>
> \newcommand{\IXr}[1]{\index{#1}\hlindex{#1}} % put as is into general index
Much better, thank you! I pushed this change out with \IXr.
> And this addition of QQ and glossary entries looks helpful to me!
Glad you like it!
Thanx, Paul
> Thanks, Akira
>
> >
> > Thanx, Paul
> >
> >> + A pointer to RCU-protected data.
> >> + Such pointers must be handled carefully, for example, any reader
> >> + that intends to dereference an RCU-protected pointer must
> >> + use \co{rcu_dereference()} (or stronger) to load that pointer,
> >> + and any updater must use \co{rcu_assign_pointer()} (or stronger)
> >> + to store to that pointer.
> >> \item[Read-Copy Update (RCU):]\glsuseri{rcu}
> >> A synchronization mechanism that can be thought of as a replacement
> >> for reader-writer locking or reference counting.
