by Paul E. McKenney

[permalink] [raw]

Subject: Re: [PATCH tip/core/rcu 1/8] documentation: Record RCU requirements

On Fri, Dec 04, 2015 at 05:54:31PM -0800, Paul E. McKenney wrote:
> On Fri, Dec 04, 2015 at 04:34:43PM -0800, Josh Triplett wrote:
> > The content of the document seems fine; a few comments below on
> > meta-issues.
> >
> > On Fri, Dec 04, 2015 at 03:50:19PM -0800, Paul E. McKenney wrote:
> > > --- /dev/null
> > > +++ b/Documentation/RCU/Design/Requirements/Requirements.html
> > > @@ -0,0 +1,2799 @@
> > > +
> > > +
> > > +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
> > > + "http://www.w3.org/TR/html4/loose.dtd">
> >
> > Nit: these days, this should just be:
> > <!doctype html>
>
> Will making this change mean that https://validator.w3.org/ will
> then require me to make a huge quantity of other changes?

I checked a prominent web site, and they are using the same doctype as
I am, so I am keeping this one. However...

> > > + <html>
> > > + <head><title>A Tour Through RCU's Requirements [LWN.net]</title>
> > > + <meta HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
> >
> > Is there a good reason to not use charset=utf-8 here?
>
> Beats me. Cargo-culted that one. ;-)

... they use utf-8, so I changed mine accordingly.

> > > +
> > > +<h1>A Tour Through RCU's Requirements</h1>
> > > +
> > > +<p>Copyright IBM Corporation, 2015</p>
> >
> > If you're aiming for a properly formatted copyright notice, the year
> > typically comes first, followed by the copyright holder. That said,
> > your corporate guidelines presumably have a specific format; is this
> > that format?
>
> Indeed it is. Between you and IBM Legal, I unfortunately must follow
> IBM Legal's advice. ;-)
>
> > > +<p>Author: Paul E. McKenney</p>
> > > +<p><i>The initial version of this document appeared in the
> > > +<a href="http://lwn.net/">LWN</a> articles
> > > +<a href="http://lwn.net/Articles/652156/">here</a>,
> > > +<a href="http://lwn.net/Articles/652677/">here</a>, and
> > > +<a href="http://lwn.net/Articles/653326/">here</a>.</i></p>
> >
> > s/http/https/g
>
> Will change.

And done, globally, at least for those whose webservers were willing to
put up with the change. Which was the vast majority.

[ . . . ]

> > > +<p>
> > > +This all should be quite obvious, but the fact remains that
> > > +Linus Torvalds recently had to
> > > +<a href="http://marc.info/?l=linux-kernel&m=142905739823385">remind</a>
> > > +me of this requirement.
> >
> > I'd suggest using the lkml.kernel.org redirector for this link, along
> > with a Message-Id.
> >
> > > +<p>
> > > +The name notwithstanding, some Linux-kernel architectures
> > > +can have nested NMIs, which RCU must handle correctly.
> > > +Andy Lutomirski
> > > +<a href="https://lkml.org/lkml/2014/11/21/642">surprised me</a>
> > > +with this requirement;
> > > +he also kindly surprised me with
> > > +<a href="https://lkml.org/lkml/2014/11/22/1">an algorithm</a>
> > > +that meets this requirement.
> >
> > These links should both use lkml.kernel.org as well. Doubly important
> > because lkml.org is often down or has broken messages in its archive.
>
> Good point, will look into finding the Message-IDs...

This involves a second click for https://lkml.kernel.org/r/<Message-ID>
Trying https://lkml.kernel.org/g/<Message-ID>. Which works nicely, so sold!

I will let you bug kernel.org about the fact that it translates the URL
to the http: form rather than the https: form... But if it did that for
the /g/ form, it couldn't find the web page. Never mind!

So all the ones that work have been converted.

Thanx, Paul

2015-12-05 21:18:30

by Paul E. McKenney

[permalink] [raw]

Subject: Re: [PATCH tip/core/rcu 1/8] documentation: Record RCU requirements

On Fri, Dec 04, 2015 at 05:56:01PM -0800, Paul E. McKenney wrote:
> On Fri, Dec 04, 2015 at 04:38:42PM -0800, Josh Triplett wrote:

[ . . . ]

> > Because you don't want to complicate the script, or because you don't
> > want to accidentally edit the wrong version? (Note that a carefully
> > written script would mean it doesn't matter which version you edit.)
>
> I prefer the simpler script.
>
> > A third alternative would be to include the answers inline right after
> > the questions, and optionally add a tiny bit of JavaScript that hides
> > them by default and lets you click to show the answer. :)
>
> That does have some advantages. I would welcome a patch that added
> the JavaScript.

And I did try a CSS approach with this CSS definition:

<style media="screen" type="text/css">
.quick-quiz-wrap {
position: relative;
}
.quick-quiz-wrap .quick-quiz-content {
display: none;
position: absolute;
bottom: -10px;
left: 10px;
right: 10px;
background-color: lightgrey;
padding: 20px;
}
.quick-quiz-wrap:hover .quick-quiz-content {
display: block;
}
</style>

I linked to this as follows:

<link rel="stylesheet" type="text/css" href="../quick-quiz.css" media="screen">

And used it like this:

<p><b>Quick Quiz:</b>
Wait a minute!
You said that updaters can make useful forward progress concurrently
with readers, but pre-existing readers will block
<tt>synchronize_rcu()</tt>!!!
Just who are you trying to fool???
</p>

<div class="quick-quiz-wrap">
<b>Quick Quiz Answer</b>
<div class="quick-quiz-content">
<p>First, if updaters do not wish to be blocked
by readers, they can use <tt>call_rcu()</tt> or
<tt>kfree_rcu()</tt>, which will be discussed later.
Second, even when using <tt>synchronize_rcu()</tt>,
the other update-side code does run concurrently with
readers, whether pre-existing or not.
</div>
</div>

This proved fragile. It worked in trivial cases, but with non-trivial
content in a non-trivial document, it refused to show anything on mouse
hover. Even in trivial cases, it sometimes made strange choices on
where to display the text. At this point, I drop back to the old-school
scripted approach. It has the advantage of working consistently and
providing good user experience, with the HTML unconditionally present. ;-)

Thanx, Paul