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?
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.
