Message-ID: <feb61ff6-f232-46ff-9c75-4d74748106ed@paulmck-laptop>
Date: Thu, 8 Jan 2026 18:23:40 -0800
From: "Paul E. McKenney" <paulmck@...nel.org>
To: Theodore Tso <tytso@....edu>
Cc: "Dr. David Alan Gilbert" <dave@...blig.org>,
	Steven Rostedt <rostedt@...dmis.org>,
	Julia Lawall <julia.lawall@...ia.fr>,
	Sasha Levin <sashal@...nel.org>,
	Gabriele Paoloni <gpaoloni@...hat.com>,
	Kate Stewart <kstewart@...uxfoundation.org>,
	Chuck Wolber <chuckwolber@...il.com>,
	Dmitry Vyukov <dvyukov@...gle.com>,
	Mark Rutland <mark.rutland@....com>,
	Thomas Gleixner <tglx@...utronix.de>,
	Lorenzo Stoakes <lorenzo.stoakes@...cle.com>,
	Shuah Khan <skhan@...uxfoundation.org>, Chris Mason <clm@...a.com>,
	linux-kernel@...r.kernel.org
Subject: Re: Follow-up on Linux-kernel code accessibility

On Mon, Dec 29, 2025 at 06:50:10PM -0500, Theodore Tso wrote:
> On Mon, Dec 29, 2025 at 10:59:12AM -0800, Paul E. McKenney wrote:
> > > Or do they actually feel like improving RCU.
> > > If they actually want to improve RCU then sure the prerequisities
> > > involve reading every reasonable piece of RCU docs; but in the other
> > > cases?  Don't make it too hard.
> > 
> > I only get 24 hours in each day, my friend.  Experience has shown that
> > there are way more people struggling with code using RCU than with code
> > implementing RCU, so the former get priority.  I could hit you with a
> > Spock quote from a certain movie, if you would like.  ;-)
> 
> ,.. and that's why I was recalling the comment, "You are not expected
> to understand this" and asking the question of which audience are we
> trying to make the code more accessible for, at least first.
> 
> Yes, it would be good if there were more than one person who can
> understand the details of the code and who can maintain it, so we
> don't have teh bus factor == 1 problem.  But the fact remains that are
> many parts of the kernel that I will freely admit that I have no
> *clue* how it work, and that's OK.  I'm sure if I spent a few weeks
> deeply meditating on the code, I could eventually figure it out ---
> but I don't have that kind of spare time.  Nor am I someone who is
> going to insist on a lot of documentation of internal details, since I
> happen to believe, like you, that accessibility to *users* of RCU is
> more important that people who are curious about the internal details
> about why we are dividing by 3, and not 4 (and 5 is right out) :-)

We are making good (if slow) progress on Linux-kernel RCU's bus number.
For but one example, I have sent only the one RCU pull request to Linus
this year (v6.18).  Uladzislau Rezki sent v6.14, Boqun Feng v6.15, Joel
Fernandes v6.16, Neeraj Upadhyay v6.17, and Frederic Weisbecker v6.19.

Things are not yet perfect, but I would say that the bus number of
all parts of the RCU implementation itself is greater than two, with
substantial portions having a much higher bus number.   This was in
part due to our having done a line-by-line walkthrough of the code,
which did result in some greatly improved comments, in case you were
wondering why I am insisting on walkthroughs for changes to comments.

And there are even some parts or RCU that have been written primarily
by someone other than me.

Much of the RCU test code, especially the rcutorture scripting under
tools, might still be at a bus number of 1, but that is a work in
progress.  Plus this scripting should be easier for an RCU newbie to
pick up.  To me, it seemed the highest priorities were:  (1) Increasing
the bus number of the actual RCU implementation and (2) Getting Linus
used to taking pull requests from not-me.  The next step`is getting the
RCU proteges more comfortable curating RCU patches.

>      	     	 	     	    	  - Ted
> 
> P.S.  If someone wants to spend time being the John Lions for RCU,
> great!  But that should be someone's passion project, and not
> necessarily highest priority for the community at large.

I tried, I really did, and not once but twice.

The first time was in the first edition of "Is Parallel Programming Hard,
And, If So, What Can You Do About it?".  This was of course stupid due to
version skew between the book and the kernel.  The second time was partly
successful, and you can see the results in Documentation/RCU/Design.
Both times I was under the mistaken impression that the RCU implementation
would not be changing much going forward.  I have since learned to ignore
that false feeling of completion.  ;-)

On the other hand, some substantial updates to this documentation were
more recently done by not-me, so maybe there is hope longer term.

Part of the problem is of course that I have not had the experience of
having been taught RCU.  I guess from that viewpoint, the real surprise
is that so many people are successfully using it.

In the meantime, I have continued on user documentation, with which I have
more than three decades of experience, getting RCU into the C++ standard,
helping Mathieu with userspace RCU (but this is mostly his baby by now),
and so on.  Current projects include an entry-level userspace RCU doc
for newbies and helping someone get an RCU implementation into libstdc++.

And these efforts really do add up.  For example, one of my children's
old high-school classmates recently started using RCU in userspace with
no help from me, just from the available documentation.

So there is significant reason for hope  ;-)

							Thanx, Paul

Powered by blists - more mailing lists