Re: [GIT PULL] RCU changes for v4.6

[Paul E. McKenney]

On Tue, Mar 15, 2016 at 09:58:19AM -0700, Linus Torvalds wrote:
> On Tue, Mar 15, 2016 at 8:33 AM, Paul E. McKenney
> <paulmck@xxxxxxxxxxxxxxxxxx> wrote:
> >
> > Good point!  I will send a pull of the documentation commits that do not
> > involve Documentation/RCU/Design.
> 
> Note that I have no objections what-so-ever with the html in the
> Design doc directory: I think using html and svg's to do the boxes and
> things is fine. Using html and svg's because you can do better
> graphics for showing real technical relationships is absolutely
> *fine*.
> 
> What I object to is "cute". We had a cartoonish jpeg at some point
> (maybe it's still there, I didn't check), and now the quizzes with the
> html filtering and checking in both versions etc.
> 
> I think "cute" may well be fine for doing presentations etc.
> 
> But I don't think it's something we want in the kernel sources, and it
> absolutely isn't when it adds big files (whether they be duplicate
> info or jpeg's) or special non-standard file formats.
> 
> It ends up being actively detrimental to disseminating the
> information, because of the conversion scripts, or because it's just
> distracting.

There is indeed a cartoon in the Requirements documentation, as well
as a simple diagram that can just as easily be represented with text.
(What can I say?  I had that .svg lying around and was feeling lazy.)
The commit at the end of this email removes them, and I have queued it
for 3.7.

On the html/htmlx duplication, understood.  I will fix this.

On the quick quizzes, if you want me to get rid of them, they are gone.

However, they really do have a serious purpose.  That purpose is to
help readers understand what they do and do not know, which admittedly
is the sort of help that many people might rather do without.  I learned
about this the hard way, while taking a class in a familiar subject some
years back.  I read the first chapter of the text, and was surprised to
find that I could answer only about 30% of the questions.  Yes, I did
re-read the chapter more carefully, and then was able to easily answer
all the questions.

The point is that after reading the chapter the first time, I thought
I knew the material, but I very clearly did not.  The quick quizzes are
intended to provide this same service to others, unwelcome though that
might be.

But again, if you don't want them, I will get rid of them.  After all,
at the time that they become critically important, I won't be in a
position to be worried about it.  ;-)

							Thanx, Paul

------------------------------------------------------------------------

commit 4fc4c42836db14c1a7ba8558cfab6db82bfe79b5
Author: Paul E. McKenney <paulmck@xxxxxxxxxxxxxxxxxx>
Date:   Tue Mar 15 11:03:36 2016 -0700

    documentation: Remove unnecessary images from requirements
    
    This commit removes a cutesy cartoon and also a diagram that can
    just as easily be represented by text.
    
    Reported-by: Linus Torvalds <torvalds@xxxxxxxxxxxxxxxxxxxx>
    Signed-off-by: Paul E. McKenney <paulmck@xxxxxxxxxxxxxxxxxx>

diff --git a/Documentation/RCU/Design/Requirements/2013-08-is-it-dead.png b/Documentation/RCU/Design/Requirements/2013-08-is-it-dead.png
deleted file mode 100644
index 7496a55e4e7b..000000000000
diff --git a/Documentation/RCU/Design/Requirements/RCUApplicability.svg b/Documentation/RCU/Design/Requirements/RCUApplicability.svg
deleted file mode 100644
index ebcbeee391ed..000000000000
diff --git a/Documentation/RCU/Design/Requirements/Requirements.html b/Documentation/RCU/Design/Requirements/Requirements.html
index 01e12b86e81f..c67a96a2a389 100644
--- a/Documentation/RCU/Design/Requirements/Requirements.html
+++ b/Documentation/RCU/Design/Requirements/Requirements.html
@@ -1120,12 +1120,27 @@ These classes is covered in the following sections.
 <h3><a name="Specialization">Specialization</a></h3>
 
 <p>
-RCU is and always has been intended primarily for read-mostly situations, as
-illustrated by the following figure.
-This means that RCU's read-side primitives are optimized, often at the
+RCU is and always has been intended primarily for read-mostly situations,
+which means that RCU's read-side primitives are optimized, often at the
 expense of its update-side primitives.
+Experience thus far is captured by the following list of situations:
 
-<p><img src="RCUApplicability.svg" alt="RCUApplicability.svg" width="70%"></p>
+<ol>
+<li>	Read-mostly data, where stale and inconsistent data is not
+	a problem:   RCU works great!
+<li>	Read-mostly data, where data must be consistent:
+	RCU works well.
+<li>	Read-write data, where data must be consistent:
+	RCU <i>might</i> work OK.
+	Or not.
+<li>	Write-mostly data, where data must be consistent:
+	RCU is very unlikely to be the right tool for the job,
+	with the following exceptions, where RCU can provide:
+	<ol type=a>
+	<li>	Existence guarantees for update-friendly mechanisms.
+	<li>	Wait-free read-side primitives for real-time use.
+	</ol>
+</ol>
 
 <p>
 This focus on read-mostly situations means that RCU must interoperate
@@ -1171,10 +1186,7 @@ some period of time, so the exact wait period is a judgment call.
 One of our pair of veternarians might wait 30 seconds before pronouncing
 the cat dead, while the other might insist on waiting a full minute.
 The two veternarians would then disagree on the state of the cat during
-the final 30 seconds of the minute following the last heartbeat, as
-fancifully illustrated below:
-
-<p><img src="2013-08-is-it-dead.png" alt="2013-08-is-it-dead.png" width="431"></p>
+the final 30 seconds of the minute following the last heartbeat.
 
 <p>
 Interestingly enough, this same situation applies to hardware.
diff --git a/Documentation/RCU/Design/Requirements/Requirements.htmlx b/Documentation/RCU/Design/Requirements/Requirements.htmlx
index 3355f1f9384c..d6a84f3e0451 100644
--- a/Documentation/RCU/Design/Requirements/Requirements.htmlx
+++ b/Documentation/RCU/Design/Requirements/Requirements.htmlx
@@ -1257,12 +1257,27 @@ These classes is covered in the following sections.
 <h3><a name="Specialization">Specialization</a></h3>
 
 <p>
-RCU is and always has been intended primarily for read-mostly situations, as
-illustrated by the following figure.
-This means that RCU's read-side primitives are optimized, often at the
+RCU is and always has been intended primarily for read-mostly situations,
+which means that RCU's read-side primitives are optimized, often at the
 expense of its update-side primitives.
+Experience thus far is captured by the following list of situations:
 
-<p><img src="RCUApplicability.svg" alt="RCUApplicability.svg" width="70%"></p>
+<ol>
+<li>	Read-mostly data, where stale and inconsistent data is not
+	a problem:   RCU works great!
+<li>	Read-mostly data, where data must be consistent:
+	RCU works well.
+<li>	Read-write data, where data must be consistent:
+	RCU <i>might</i> work OK.
+	Or not.
+<li>	Write-mostly data, where data must be consistent:
+	RCU is very unlikely to be the right tool for the job,
+	with the following exceptions, where RCU can provide:
+	<ol type=a>
+	<li>	Existence guarantees for update-friendly mechanisms.
+	<li>	Wait-free read-side primitives for real-time use.
+	</ol>
+</ol>
 
 <p>
 This focus on read-mostly situations means that RCU must interoperate
@@ -1330,10 +1345,7 @@ some period of time, so the exact wait period is a judgment call.
 One of our pair of veternarians might wait 30 seconds before pronouncing
 the cat dead, while the other might insist on waiting a full minute.
 The two veternarians would then disagree on the state of the cat during
-the final 30 seconds of the minute following the last heartbeat, as
-fancifully illustrated below:
-
-<p><img src="2013-08-is-it-dead.png" alt="2013-08-is-it-dead.png" width="431"></p>
+the final 30 seconds of the minute following the last heartbeat.
 
 <p>
 Interestingly enough, this same situation applies to hardware.