Re: A few comments on new Section 9.5.1.2 "Core RCU API"

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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

And this addition of QQ and glossary entries looks helpful to me!

        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.



[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Index of Archives]     [Linux NFS]     [Linux NILFS]     [Linux USB Devel]     [Video for Linux]     [Linux Audio Users]     [Yosemite News]     [Linux Kernel]     [Linux SCSI]

  Powered by Linux