Re: [Linux-kernel-mentees] [PATCH] Documentation: RCU: arrayRCU: Converted arrayRCU.txt to arrayRCU.rst

["Paul E. McKenney" <paulmck@kernel.org>]

On Tue, Nov 05, 2019 at 08:49:47PM +0700, Phong Tran wrote:
> On 10/29/19 3:24 AM, madhuparnabhowmik04@gmail.com wrote:
> > From: Madhuparna Bhowmik <madhuparnabhowmik04@gmail.com>
> > 
> > This patch converts arrayRCU from txt to rst format.
> > arrayRCU.rst is also added in the index.rst file.
> > 
> > Signed-off-by: Madhuparna Bhowmik <madhuparnabhowmik04@gmail.com>
> > ---
> >   .../RCU/{arrayRCU.txt => arrayRCU.rst}         | 18 +++++++++++++-----
> >   Documentation/RCU/index.rst                    |  1 +
> >   2 files changed, 14 insertions(+), 5 deletions(-)
> >   rename Documentation/RCU/{arrayRCU.txt => arrayRCU.rst} (91%)
> > 
> > diff --git a/Documentation/RCU/arrayRCU.txt b/Documentation/RCU/arrayRCU.rst
> > similarity index 91%
> > rename from Documentation/RCU/arrayRCU.txt
> > rename to Documentation/RCU/arrayRCU.rst
> > index f05a9afb2c39..ed5ae24b196e 100644
> > --- a/Documentation/RCU/arrayRCU.txt
> > +++ b/Documentation/RCU/arrayRCU.rst
> > @@ -1,5 +1,7 @@
> > -Using RCU to Protect Read-Mostly Arrays
> > +.. _array_rcu_doc:
> > +Using RCU to Protect Read-Mostly Arrays
> > +=======================================
> >   Although RCU is more commonly used to protect linked lists, it can
> >   also be used to protect arrays.  Three situations are as follows:
> > @@ -26,6 +28,7 @@ described in the following sections.
> 
> It will be better to have the cross reference for each situation.
> 
> Hash Tables
> Static Arrays
> Resizeable Arrays

Madhuparna, could you please put a patch together creating these
cross-references and handling Phong's comments below (probably
by getting rid of the "." so that the resulting ":" doesn't look
strange)?

Then I will fold that patch into your original commit in -rcu and
add Phong's Tested-by.

							Thanx, Paul

> >   Situation 1: Hash Tables
> > +------------------------
> >   Hash tables are often implemented as an array, where each array entry
> >   has a linked-list hash chain.  Each hash chain can be protected by RCU
> > @@ -34,6 +37,7 @@ to other array-of-list situations, such as radix trees.
> >   Situation 2: Static Arrays
> > +--------------------------
> >   Static arrays, where the data (rather than a pointer to the data) is
> >   located in each array element, and where the array is never resized,
> > @@ -41,11 +45,13 @@ have not been used with RCU.  Rik van Riel recommends using seqlock in
> >   this situation, which would also have minimal read-side overhead as long
> >   as updates are rare.
> > -Quick Quiz:  Why is it so important that updates be rare when
> > -	     using seqlock?
> > +Quick Quiz:
> > +		Why is it so important that updates be rare when using seqlock?
> > +:ref:`Answer to Quick Quiz <answer_quick_quiz_seqlock>`
> >   Situation 3: Resizeable Arrays
> > +------------------------------
> >   Use of RCU for resizeable arrays is demonstrated by the grow_ary()
> >   function formerly used by the System V IPC code.  The array is used
> > @@ -60,7 +66,7 @@ the remainder of the new, updates the ids->entries pointer to point to
> >   the new array, and invokes ipc_rcu_putref() to free up the old array.
> >   Note that rcu_assign_pointer() is used to update the ids->entries pointer,
> >   which includes any memory barriers required on whatever architecture
> > -you are running on.
> > +you are running on.::
> 
> a redundant ":" in here with html page.
> 
> 
> 
> 
> >   	static int grow_ary(struct ipc_ids* ids, int newsize)
> >   	{
> > @@ -112,7 +118,7 @@ a simple check suffices.  The pointer to the structure corresponding
> >   to the desired IPC object is placed in "out", with NULL indicating
> >   a non-existent entry.  After acquiring "out->lock", the "out->deleted"
> >   flag indicates whether the IPC object is in the process of being
> > -deleted, and, if not, the pointer is returned.
> > +deleted, and, if not, the pointer is returned.::
> 
> same as above
> 
> 
> Tested-by: Phong Tran <tranmanphong@gmail.com>
> 
> Regards,
> Phong.
> 
> >   	struct kern_ipc_perm* ipc_lock(struct ipc_ids* ids, int id)
> >   	{
> > @@ -144,8 +150,10 @@ deleted, and, if not, the pointer is returned.
> >   		return out;
> >   	}
> > +.. _answer_quick_quiz_seqlock:
> >   Answer to Quick Quiz:
> > +	Why is it so important that updates be rare when using seqlock?
> >   	The reason that it is important that updates be rare when
> >   	using seqlock is that frequent updates can livelock readers.
> > diff --git a/Documentation/RCU/index.rst b/Documentation/RCU/index.rst
> > index 5c99185710fa..8d20d44f8fd4 100644
> > --- a/Documentation/RCU/index.rst
> > +++ b/Documentation/RCU/index.rst
> > @@ -7,6 +7,7 @@ RCU concepts
> >   .. toctree::
> >      :maxdepth: 3
> > +   arrayRCU
> >      rcu
> >      listRCU
> >      UP
> >