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
> <paul...@linux.vnet.ibm.com> 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 <paul...@linux.vnet.ibm.com>
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 <torva...@linux-foundation.org>
Signed-off-by: Paul E. McKenney <paul...@linux.vnet.ibm.com>
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.
