* [PATCH -perfbook v2 1/9] Annotate mid-sentence and end-of-sentence periods
2021-04-27 15:18 [PATCH -perfbook v2 0/9] Add script to check period spacing Akira Yokosawa
@ 2021-04-27 15:20 ` Akira Yokosawa
2021-04-27 15:22 ` [PATCH -perfbook v2 2/9] periodcheck: Add script to check missing annotation of period Akira Yokosawa
` (8 subsequent siblings)
9 siblings, 0 replies; 15+ messages in thread
From: Akira Yokosawa @ 2021-04-27 15:20 UTC (permalink / raw)
To: Paul E. McKenney; +Cc: perfbook, Akira Yokosawa
These were caught by the check script to be added in
the following updates.
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
ack.tex | 2 +-
advsync/rt.tex | 2 +-
howto/howto.tex | 2 +-
locking/locking.tex | 2 +-
4 files changed, 4 insertions(+), 4 deletions(-)
diff --git a/ack.tex b/ack.tex
index b8cffa37..ce64d325 100644
--- a/ack.tex
+++ b/ack.tex
@@ -126,4 +126,4 @@ organizations that keep Internet and the World Wide Web up and running,
and this one is no exception.
Portions of this material are based upon work supported by the National
-Science Foundation under Grant No. CNS-0719851.
+Science Foundation under Grant No.\@ CNS-0719851.
diff --git a/advsync/rt.tex b/advsync/rt.tex
index bb8465ff..71ab0661 100644
--- a/advsync/rt.tex
+++ b/advsync/rt.tex
@@ -573,7 +573,7 @@ as depicted in
\cref{fig:advsync:Real-Time Reflexes}.
The hard real-time reflexes, which read from sensors and control
actuators, run real-time on a single CPU or on special-purpose hardware
-such as an FPGA.
+such as an FPGA\@.
The non-real-time strategy and planning portion of the application runs
on the remaining CPUs.
Strategy and planning activities might include statistical analysis,
diff --git a/howto/howto.tex b/howto/howto.tex
index c3d0a101..0f0ba293 100644
--- a/howto/howto.tex
+++ b/howto/howto.tex
@@ -304,7 +304,7 @@ Fortunately, there are many alternatives available to you:
\pplsur{Victor}{Luchangco}, and \pplsur{Michael}{Spear} did
catch up in their second edition by adding short sections on
hazard pointers and on \acr{rcu}, with the latter in the guise
- of \acr{ebr}.
+ of \acr{ebr}\@.
They also include a brief history of both, albeit with an
abbreviated history of \acr{rcu} that picks up almost a year after
it was accepted into the Linux kernel and more than 20~years
diff --git a/locking/locking.tex b/locking/locking.tex
index 5313f926..6bc93e49 100644
--- a/locking/locking.tex
+++ b/locking/locking.tex
@@ -713,7 +713,7 @@ outside of a signal handler without blocking signals.
handler without blocking signals, a signal might be handled while
holding this lock.
The corresponding signal handler might then acquire
- Lock~B, so that Lock~B is acquired while holding Lock~A.
+ Lock~B, so that Lock~B is acquired while holding Lock~A\@.
Therefore, if we also acquire Lock~A while holding Lock~B,
we will have a deadlock cycle.
Note that this problem exists even if signals are blocked while
--
2.17.1
^ permalink raw reply related [flat|nested] 15+ messages in thread* [PATCH -perfbook v2 2/9] periodcheck: Add script to check missing annotation of period
2021-04-27 15:18 [PATCH -perfbook v2 0/9] Add script to check period spacing Akira Yokosawa
2021-04-27 15:20 ` [PATCH -perfbook v2 1/9] Annotate mid-sentence and end-of-sentence periods Akira Yokosawa
@ 2021-04-27 15:22 ` Akira Yokosawa
2021-04-27 15:24 ` [PATCH -perfbook v2 3/9] periodcheck: Add check of nbsp in front of \cite{} Akira Yokosawa
` (7 subsequent siblings)
9 siblings, 0 replies; 15+ messages in thread
From: Akira Yokosawa @ 2021-04-27 15:22 UTC (permalink / raw)
To: Paul E. McKenney; +Cc: perfbook, Akira Yokosawa
"make periodcheck" will do the check.
NOTE: Possible false negative/positive as of this commit:
o A mid-sentence period is ignored when the line matches "\label{"
or "\*ref{" pattern. It should be caught when it is outside a
macro.
o \cref{} can have comma-separated multiple labels as an argument.
When one of the labels has a mid-sentence period and on a
subsequent line in the input, it is not ignored.
o \crefrange{}{} can also have a label string on a subsequent line.
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
Makefile | 5 ++-
utilities/periodcheck.pl | 76 ++++++++++++++++++++++++++++++++++++++++
utilities/periodcheck.sh | 20 +++++++++++
3 files changed, 100 insertions(+), 1 deletion(-)
create mode 100755 utilities/periodcheck.pl
create mode 100755 utilities/periodcheck.sh
diff --git a/Makefile b/Makefile
index 4beb2c17..ea264dc5 100644
--- a/Makefile
+++ b/Makefile
@@ -192,7 +192,7 @@ BASE_DEPENDS := perfbook.tex $(foreach v,tcb 1c msns mss mstx msr msn msnt sf nq
.PHONY: qq perfbook-qq.pdf qqmsg
.PHONY: help help-official help-full help-semiofficial help-paper help-draft
.PHONY: help-experimental help-prefixed
-.PHONY: paper-clean
+.PHONY: paper-clean periodcheck
all: $(targ)
@@ -611,5 +611,8 @@ ls-unused:
neatfreak: distclean
find . -name '*.pdf' | xargs rm -f
+periodcheck:
+ utilities/periodcheck.sh
+
.SECONDEXPANSION:
$(ABBREVTARGETS): %: perfbook-$$@.pdf
diff --git a/utilities/periodcheck.pl b/utilities/periodcheck.pl
new file mode 100755
index 00000000..225391ff
--- /dev/null
+++ b/utilities/periodcheck.pl
@@ -0,0 +1,76 @@
+#!/usr/bin/perl
+# SPDX-License-Identifier: GPL-2.0-or-later
+#
+# Check LaTeX source of mid-sentence and end-of-sentence period
+#
+# Assumptions:
+# End-of-sentence periods are at the end of input lines.
+#
+# Exceptions:
+# LaTeX comments
+# LaTeX labels: such as \cref{fig:xxx:foo vs. bar}
+# Verbatim contents
+# Table contents
+#
+# Copyright (C) Akira Yokosawa, 2021
+#
+# Authors: Akira Yokosawa <akiyks@gmail.com>
+
+use strict;
+use warnings;
+
+my $line;
+my $next_line;
+my $line_num = 0;
+my $skip = 0;
+my $safe = 0;
+my $Verbatim_begin = qr/\\begin\{Verbatim/ ;
+my $Verbatim_end = qr/\\end\{Verbatim/ ;
+my $tabular_begin = qr/\\begin\{tabula/ ;
+my $tabular_end = qr/\\end\{tabula/ ;
+
+sub check_line {
+ if ($line =~ /$Verbatim_begin/ ||
+ $line =~ /$tabular_begin/) {
+ $skip = 1;
+ }
+ unless ($skip) {
+ $safe = 1;
+ if ($line =~ /^(?=[\s]*+[^%])[^%]*[A-Z]\.$/ ||
+ $line =~ /^(?=[\s]*+[^%])[^%]*[A-Z]\.\\footnote/ ||
+ $line =~ /^(?=[\s]*+[^%])[^%]*[Aa]cr\{.+\}\.$/ ||
+ $line =~ /^(?=[\s]*+[^%])[^%]*[Aa]crm\{.+\}\.$/) {
+ $safe = 0;
+ if ($next_line =~ /^\s*$/ || $next_line =~ /^\s*%/ ||
+ $next_line =~ /\\item/ || $next_line =~ /\\end\{quot/ ||
+ $next_line =~ /\\end\{enum/ || $next_line =~ /\\end\{item/) {
+ $safe = 1;
+ }
+ }
+ if ($line =~ /^(?=[\s]*+[^%])[^%]*[a-z\}]\.\s[^\\]+/) {
+ $safe = 0;
+ if ($line =~ /ref\{/ || $line =~ /label\{/) {
+ $safe = 1;
+ }
+ }
+ unless ($safe) {
+ print $ARGV[0], ':', $line_num, ':', $line;
+ }
+ }
+ if ($line =~ /$Verbatim_end/ ||
+ $line =~ /$tabular_end/) {
+ $skip = 0;
+ }
+}
+
+open(my $fh, '<:encoding(UTF-8)', $ARGV[0])
+ or die "Could not open file '$ARGV[0]' $!";
+
+$line = <$fh>;
+$line_num = 1;
+while($next_line = <$fh>) {
+ check_line();
+ $line = $next_line;
+ $line_num++ ;
+}
+check_line();
diff --git a/utilities/periodcheck.sh b/utilities/periodcheck.sh
new file mode 100755
index 00000000..a56657f3
--- /dev/null
+++ b/utilities/periodcheck.sh
@@ -0,0 +1,20 @@
+#!/bin/sh
+
+tex_sources_all=`find . -name "*.tex" -print`
+tex_sources=""
+
+for f in $tex_sources_all
+do
+ case $f in
+ ./perfbook*) ;;
+ ./qqz*) ;;
+ ./future/HTMtable*) ;;
+ ./appendix/styleguide*) ;;
+ *) tex_sources="$tex_sources $f" ;;
+ esac
+done
+
+for g in $tex_sources
+do
+ utilities/periodcheck.pl $g
+done
--
2.17.1
^ permalink raw reply related [flat|nested] 15+ messages in thread* [PATCH -perfbook v2 3/9] periodcheck: Add check of nbsp in front of \cite{}
2021-04-27 15:18 [PATCH -perfbook v2 0/9] Add script to check period spacing Akira Yokosawa
2021-04-27 15:20 ` [PATCH -perfbook v2 1/9] Annotate mid-sentence and end-of-sentence periods Akira Yokosawa
2021-04-27 15:22 ` [PATCH -perfbook v2 2/9] periodcheck: Add script to check missing annotation of period Akira Yokosawa
@ 2021-04-27 15:24 ` Akira Yokosawa
2021-04-27 15:26 ` [PATCH -perfbook v2 4/9] periodcheck: Improve label string matching Akira Yokosawa
` (6 subsequent siblings)
9 siblings, 0 replies; 15+ messages in thread
From: Akira Yokosawa @ 2021-04-27 15:24 UTC (permalink / raw)
To: Paul E. McKenney; +Cc: perfbook, Akira Yokosawa
Also use /usr/bin/env in shebang.
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
utilities/periodcheck.pl | 8 +++++++-
1 file changed, 7 insertions(+), 1 deletion(-)
diff --git a/utilities/periodcheck.pl b/utilities/periodcheck.pl
index 225391ff..c585b147 100755
--- a/utilities/periodcheck.pl
+++ b/utilities/periodcheck.pl
@@ -1,4 +1,4 @@
-#!/usr/bin/perl
+#!/usr/bin/env perl
# SPDX-License-Identifier: GPL-2.0-or-later
#
# Check LaTeX source of mid-sentence and end-of-sentence period
@@ -53,6 +53,12 @@ sub check_line {
$safe = 1;
}
}
+ if ($line =~ /^(?=[\s]*+[^%])[^%]*[^~]\\cite/) {
+ $safe = 0;
+ if ($line =~ /^(?=[\s]*+[^%])[^%]*~\(\\cite/) {
+ $safe = 1;
+ }
+ }
unless ($safe) {
print $ARGV[0], ':', $line_num, ':', $line;
}
--
2.17.1
^ permalink raw reply related [flat|nested] 15+ messages in thread* [PATCH -perfbook v2 4/9] periodcheck: Improve label string matching
2021-04-27 15:18 [PATCH -perfbook v2 0/9] Add script to check period spacing Akira Yokosawa
` (2 preceding siblings ...)
2021-04-27 15:24 ` [PATCH -perfbook v2 3/9] periodcheck: Add check of nbsp in front of \cite{} Akira Yokosawa
@ 2021-04-27 15:26 ` Akira Yokosawa
2021-04-27 15:28 ` [PATCH -perfbook v2 5/9] periodcheck: Replace escaped percent symbol first Akira Yokosawa
` (5 subsequent siblings)
9 siblings, 0 replies; 15+ messages in thread
From: Akira Yokosawa @ 2021-04-27 15:26 UTC (permalink / raw)
To: Paul E. McKenney; +Cc: perfbook, Akira Yokosawa
Instead of patterns "\label" and "ref{", use a regex pattern
to match "foo:bar:Label String" and do checks after removing
label strings.
There still remains an assumption that each label string completes
within an input line.
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
utilities/periodcheck.pl | 13 +++++++++----
utilities/periodcheck.sh | 3 +++
2 files changed, 12 insertions(+), 4 deletions(-)
diff --git a/utilities/periodcheck.pl b/utilities/periodcheck.pl
index c585b147..27871507 100755
--- a/utilities/periodcheck.pl
+++ b/utilities/periodcheck.pl
@@ -28,8 +28,16 @@ my $Verbatim_begin = qr/\\begin\{Verbatim/ ;
my $Verbatim_end = qr/\\end\{Verbatim/ ;
my $tabular_begin = qr/\\begin\{tabula/ ;
my $tabular_end = qr/\\end\{tabula/ ;
+my $label_ptn = qr/(^|\{)(,?[a-z]{3}:[a-zMPS]+:[^\},]+)(\}|,)/ ;
sub check_line {
+ my $line_raw = $line;
+ if ($line =~ /$label_ptn/) {
+ while ($line && $line =~ /$label_ptn/) {
+ my $quoted_2 = quotemeta $2;
+ $line =~ s/$quoted_2//;
+ }
+ }
if ($line =~ /$Verbatim_begin/ ||
$line =~ /$tabular_begin/) {
$skip = 1;
@@ -49,9 +57,6 @@ sub check_line {
}
if ($line =~ /^(?=[\s]*+[^%])[^%]*[a-z\}]\.\s[^\\]+/) {
$safe = 0;
- if ($line =~ /ref\{/ || $line =~ /label\{/) {
- $safe = 1;
- }
}
if ($line =~ /^(?=[\s]*+[^%])[^%]*[^~]\\cite/) {
$safe = 0;
@@ -60,7 +65,7 @@ sub check_line {
}
}
unless ($safe) {
- print $ARGV[0], ':', $line_num, ':', $line;
+ print $ARGV[0], ':', $line_num, ':', $line_raw;
}
}
if ($line =~ /$Verbatim_end/ ||
diff --git a/utilities/periodcheck.sh b/utilities/periodcheck.sh
index a56657f3..d6cd7510 100755
--- a/utilities/periodcheck.sh
+++ b/utilities/periodcheck.sh
@@ -8,6 +8,9 @@ do
case $f in
./perfbook*) ;;
./qqz*) ;;
+ ./glsdict.tex) ;;
+ ./origpub.tex) ;;
+ ./contrib.tex) ;;
./future/HTMtable*) ;;
./appendix/styleguide*) ;;
*) tex_sources="$tex_sources $f" ;;
--
2.17.1
^ permalink raw reply related [flat|nested] 15+ messages in thread* [PATCH -perfbook v2 5/9] periodcheck: Replace escaped percent symbol first
2021-04-27 15:18 [PATCH -perfbook v2 0/9] Add script to check period spacing Akira Yokosawa
` (3 preceding siblings ...)
2021-04-27 15:26 ` [PATCH -perfbook v2 4/9] periodcheck: Improve label string matching Akira Yokosawa
@ 2021-04-27 15:28 ` Akira Yokosawa
2021-04-27 15:29 ` [PATCH -perfbook v2 6/9] treewide: Make end-of-sentence periods be at end of lines Akira Yokosawa
` (4 subsequent siblings)
9 siblings, 0 replies; 15+ messages in thread
From: Akira Yokosawa @ 2021-04-27 15:28 UTC (permalink / raw)
To: Paul E. McKenney; +Cc: perfbook, Akira Yokosawa
To prevent "\%" from being treated as a symbol of comment,
replace it with "pct" at the beginning of pattern matching.
(Source .tex files are not modified.)
Also improve regex of label string to cache "chp:foo bar".
Add some comments and do a couple of refactoring by using
(xxx|yyy) and "?" patterns.
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
utilities/periodcheck.pl | 14 +++++++-------
1 file changed, 7 insertions(+), 7 deletions(-)
diff --git a/utilities/periodcheck.pl b/utilities/periodcheck.pl
index 27871507..b1551c44 100755
--- a/utilities/periodcheck.pl
+++ b/utilities/periodcheck.pl
@@ -28,30 +28,30 @@ my $Verbatim_begin = qr/\\begin\{Verbatim/ ;
my $Verbatim_end = qr/\\end\{Verbatim/ ;
my $tabular_begin = qr/\\begin\{tabula/ ;
my $tabular_end = qr/\\end\{tabula/ ;
-my $label_ptn = qr/(^|\{)(,?[a-z]{3}:[a-zMPS]+:[^\},]+)(\}|,)/ ;
+my $label_ptn = qr/(^\s*|\{)(,?[a-z]{3,4}:([a-zMPS]+:)?[^\},]+)(\}|,)/ ;
sub check_line {
my $line_raw = $line;
- if ($line =~ /$label_ptn/) {
+ $line =~ s/\\%/pct/g ; # replace \% to prevent false negative
+ if ($line =~ /$label_ptn/) {# remove label string
while ($line && $line =~ /$label_ptn/) {
my $quoted_2 = quotemeta $2;
$line =~ s/$quoted_2//;
}
}
if ($line =~ /$Verbatim_begin/ ||
- $line =~ /$tabular_begin/) {
+ $line =~ /$tabular_begin/) { # exception (verbatim and tabular)
$skip = 1;
}
unless ($skip) {
$safe = 1;
if ($line =~ /^(?=[\s]*+[^%])[^%]*[A-Z]\.$/ ||
$line =~ /^(?=[\s]*+[^%])[^%]*[A-Z]\.\\footnote/ ||
- $line =~ /^(?=[\s]*+[^%])[^%]*[Aa]cr\{.+\}\.$/ ||
- $line =~ /^(?=[\s]*+[^%])[^%]*[Aa]crm\{.+\}\.$/) {
+ $line =~ /^(?=[\s]*+[^%])[^%]*[Aa]crm?\{.+\}\.$/ ) {
$safe = 0;
if ($next_line =~ /^\s*$/ || $next_line =~ /^\s*%/ ||
- $next_line =~ /\\item/ || $next_line =~ /\\end\{quot/ ||
- $next_line =~ /\\end\{enum/ || $next_line =~ /\\end\{item/) {
+ $next_line =~ /\\item/ ||
+ $next_line =~ /\\end\{(quot|enum|item|sequ)/ ) {
$safe = 1;
}
}
--
2.17.1
^ permalink raw reply related [flat|nested] 15+ messages in thread* [PATCH -perfbook v2 6/9] treewide: Make end-of-sentence periods be at end of lines
2021-04-27 15:18 [PATCH -perfbook v2 0/9] Add script to check period spacing Akira Yokosawa
` (4 preceding siblings ...)
2021-04-27 15:28 ` [PATCH -perfbook v2 5/9] periodcheck: Replace escaped percent symbol first Akira Yokosawa
@ 2021-04-27 15:29 ` Akira Yokosawa
2021-04-27 15:30 ` [PATCH -perfbook v2 7/9] styleguide: Make end-of-sentence periods be at the " Akira Yokosawa
` (3 subsequent siblings)
9 siblings, 0 replies; 15+ messages in thread
From: Akira Yokosawa @ 2021-04-27 15:29 UTC (permalink / raw)
To: Paul E. McKenney; +Cc: perfbook, Akira Yokosawa
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
SMPdesign/SMPdesign.tex | 36 +++---
SMPdesign/beyond.tex | 3 +-
SMPdesign/criteria.tex | 4 +-
advsync/rt.tex | 5 +-
appendix/whymb/whymemorybarriers.tex | 71 ++++++-----
count/count.tex | 11 +-
datastruct/datastruct.tex | 15 ++-
debugging/debugging.tex | 12 +-
defer/defer.tex | 4 +-
defer/hazptr.tex | 7 +-
defer/rcufundamental.tex | 5 +-
easy/easy.tex | 3 +-
formal/dyntickrcu.tex | 15 ++-
formal/ppcmem.tex | 180 ++++++++++++++-------------
formal/spinhint.tex | 148 ++++++++++++----------
glossary.tex | 9 +-
intro/intro.tex | 27 ++--
legal.tex | 9 +-
locking/locking.tex | 3 +-
memorder/memorder.tex | 12 +-
owned/owned.tex | 5 +-
together/refcnt.tex | 4 +-
toolsoftrade/toolsoftrade.tex | 3 +-
23 files changed, 332 insertions(+), 259 deletions(-)
diff --git a/SMPdesign/SMPdesign.tex b/SMPdesign/SMPdesign.tex
index 5cc566a9..7d392a84 100644
--- a/SMPdesign/SMPdesign.tex
+++ b/SMPdesign/SMPdesign.tex
@@ -174,9 +174,9 @@ global locks.\footnote{
in Section~\ref{sec:SMPdesign:Data Locking}.}
It is especially
easy to retrofit an existing program to use code locking in
-order to run it on a multiprocessor. If the program has
-only a single shared resource, code locking will even give
-optimal performance.
+order to run it on a multiprocessor.
+If the program has only a single shared resource, code locking
+will even give optimal performance.
However, many of the larger and more complex programs
require much of the execution to
occur in \IXpl{critical section}, which in turn causes code locking
@@ -184,9 +184,9 @@ to sharply limits their scalability.
Therefore, you should use code locking on programs that spend
only a small fraction of their execution time in critical sections or
-from which only modest scaling is required. In these cases,
-code locking will provide a relatively simple program that is
-very similar to its sequential counterpart,
+from which only modest scaling is required.
+In these cases, code locking will provide a relatively simple
+program that is very similar to its sequential counterpart,
as can be seen in
Listing~\ref{lst:SMPdesign:Code-Locking Hash Table Search}.
However, note that the simple return of the comparison in
@@ -498,11 +498,13 @@ Data ownership might seem arcane, but it is used very frequently:
(such as {\tt auto} variables in C
and C++) are owned by that CPU or process.
\item An instance of a user interface owns the corresponding
- user's context. It is very common for applications
- interacting with parallel database engines to be
- written as if they were entirely sequential programs.
+ user's context.
+ It is very common for applications interacting with parallel
+ database engines to be written as if they were entirely
+ sequential programs.
Such applications own the user interface and his current
- action. Explicit parallelism is thus confined to the
+ action.
+ Explicit parallelism is thus confined to the
database engine itself.
\item Parametric simulations are often trivially parallelized
by granting each thread ownership of a particular region
@@ -777,8 +779,9 @@ parallelize the common-case code path without incurring the complexity
that would be required to aggressively parallelize the entire algorithm.
You must understand not only the specific algorithm you wish
to parallelize, but also the workload that the algorithm will
-be subjected to. Great creativity and design
-effort is often required to construct a parallel fastpath.
+be subjected to.
+Great creativity and design effort is often required to construct
+a parallel fastpath.
Parallel fastpath combines different patterns (one for the
fastpath, one elsewhere) and is therefore a template pattern.
@@ -1200,8 +1203,8 @@ this book.
\begin{description}
\item[$g$] Number of blocks globally available.
\item[$i$] Number of blocks left in the initializing thread's
- per-thread pool. (This is one reason you needed
- to look at the code!)
+ per-thread pool.
+ (This is one reason you needed to look at the code!)
\item[$m$] Allocation/free run length.
\item[$n$] Number of threads, excluding the initialization thread.
\item[$p$] Per-thread maximum block consumption, including
@@ -1209,8 +1212,9 @@ this book.
remaining in the per-thread pool.
\end{description}
- The values $g$, $m$, and $n$ are given. The value for $p$ is
- $m$ rounded up to the next multiple of $s$, as follows:
+ The values $g$, $m$, and $n$ are given.
+ The value for $p$ is $m$ rounded up to the next multiple of $s$,
+ as follows:
\begin{equation}
p = s \left \lceil \frac{m}{s} \right \rceil
diff --git a/SMPdesign/beyond.tex b/SMPdesign/beyond.tex
index e308f1d5..bd0fe6f1 100644
--- a/SMPdesign/beyond.tex
+++ b/SMPdesign/beyond.tex
@@ -159,7 +159,8 @@ line~\lnref{recordnext} records this cell in the next
slot of the \co{->visited[]} array,
line~\lnref{next:visited} indicates that this slot
is now full, and line~\lnref{mark:visited} marks this cell as visited and also records
-the distance from the maze start. Line~\lnref{ret:success} then returns success.
+the distance from the maze start.
+Line~\lnref{ret:success} then returns success.
\end{fcvref}
\begin{fcvref}[ln:SMPdesign:SEQ Helper Pseudocode:find]
diff --git a/SMPdesign/criteria.tex b/SMPdesign/criteria.tex
index 0e581f15..915454e1 100644
--- a/SMPdesign/criteria.tex
+++ b/SMPdesign/criteria.tex
@@ -141,8 +141,8 @@ parallel program.
most-restrictive exclusive-lock critical section.
\item Contention effects consume the excess CPU and/or
wallclock time when the actual speedup is less than
- the number of available CPUs. The
- larger the gap between the number of CPUs
+ the number of available CPUs.
+ The larger the gap between the number of CPUs
and the actual speedup, the less efficiently the
CPUs will be used.
Similarly, the greater the desired efficiency, the smaller
diff --git a/advsync/rt.tex b/advsync/rt.tex
index 71ab0661..e939a029 100644
--- a/advsync/rt.tex
+++ b/advsync/rt.tex
@@ -1149,8 +1149,9 @@ priority-inversion conundrum:
\begin{enumerate}
\item Only allow one read-acquisition of a given reader-writer lock
- at a time. (This is the approach traditionally taken by
- the Linux kernel's \rt\ patchset.)
+ at a time.
+ (This is the approach traditionally taken by the Linux
+ kernel's \rt\ patchset.)
\item Only allow $N$ read-acquisitions of a given reader-writer lock
at a time, where $N$ is the number of CPUs.
\item Only allow $N$ read-acquisitions of a given reader-writer lock
diff --git a/appendix/whymb/whymemorybarriers.tex b/appendix/whymb/whymemorybarriers.tex
index 7ec718bb..ea9fd14b 100644
--- a/appendix/whymb/whymemorybarriers.tex
+++ b/appendix/whymb/whymemorybarriers.tex
@@ -403,7 +403,8 @@ levels of the system architecture.
responses totally saturate the system bus?
}\QuickQuizAnswerM{
It might, if large-scale multiprocessors were in fact implemented
- that way. Larger multiprocessors, particularly NUMA machines,
+ that way.
+ Larger multiprocessors, particularly NUMA machines,
tend to use so-called ``directory-based'' cache-coherence
protocols to avoid this and other problems.
}\QuickQuizEndM
@@ -413,15 +414,18 @@ levels of the system architecture.
anyway, why bother with SMP at all?
}\QuickQuizAnswerE{
There has been quite a bit of controversy on this topic over
- the past few decades. One answer is that the cache-coherence
+ the past few decades.
+ One answer is that the cache-coherence
protocols are quite simple, and therefore can be implemented
directly in hardware, gaining bandwidths and latencies
- unattainable by software message passing. Another answer is that
+ unattainable by software message passing.
+ Another answer is that
the real truth is to be found in economics due to the relative
prices of large SMP machines and that of clusters of smaller
- SMP machines. A third answer is that the SMP programming
- model is easier to use than that of distributed systems, but
- a rebuttal might note the appearance of HPC clusters and MPI\@.
+ SMP machines.
+ A third answer is that the SMP programming model is easier to
+ use than that of distributed systems, but a rebuttal might note
+ the appearance of HPC clusters and MPI\@.
And so the argument continues.
}\QuickQuizEndE
}
@@ -784,9 +788,10 @@ Suppose further that the cache line containing ``a'' resides only in CPU~1's
cache, and that the cache line containing ``b'' is owned by CPU~0.
Then the sequence of operations might be as follows:
\begin{sequence}
-\item CPU~0 executes \co{a = 1}. The cache line is not in
- CPU~0's cache, so CPU~0 places the new value of ``a'' in its
- store buffer and transmits a ``read invalidate'' message.
+\item CPU~0 executes \co{a = 1}.
+ The cache line is not in CPU~0's cache, so CPU~0 places the new
+ value of ``a'' in its store buffer and transmits a ``read
+ invalidate'' message.
\label{seq:app:whymb:Store Buffers and Memory Barriers}
\item CPU~1 executes \co{while (b == 0) continue}, but the cache line
containing ``b'' is not in its cache.
@@ -853,9 +858,10 @@ applied.
With this latter approach the sequence of operations might be as follows:
\begin{sequence}
-\item CPU~0 executes \co{a = 1}. The cache line is not in
- CPU~0's cache, so CPU~0 places the new value of ``a'' in its
- store buffer and transmits a ``read invalidate'' message.
+\item CPU~0 executes \co{a = 1}.
+ The cache line is not in CPU~0's cache, so CPU~0 places the new
+ value of ``a'' in its store buffer and transmits a ``read
+ invalidate'' message.
\item CPU~1 executes \co{while (b == 0) continue}, but the cache line
containing ``b'' is not in its cache.
It therefore transmits a ``read'' message.
@@ -1045,11 +1051,11 @@ void bar(void)
Then the sequence of operations might be as follows:
\begin{fcvref}[ln:app:whymb:Breaking mb]
\begin{sequence}
-\item CPU~0 executes \co{a = 1}. The corresponding
- cache line is read-only in
- CPU~0's cache, so CPU~0 places the new value of ``a'' in its
- store buffer and transmits an ``invalidate'' message in order
- to flush the corresponding cache line from CPU~1's cache.
+\item CPU~0 executes \co{a = 1}.
+ The corresponding cache line is read-only in CPU~0's cache, so
+ CPU~0 places the new value of ``a'' in its store buffer and
+ transmits an ``invalidate'' message in order to flush the
+ corresponding cache line from CPU~1's cache.
\label{seq:app:whymb:Invalidate Queues and Memory Barriers}
\item CPU~1 executes \co{while (b == 0) continue}, but the cache line
containing ``b'' is not in its cache.
@@ -1186,11 +1192,11 @@ void bar(void)
\begin{fcvref}[ln:app:whymb:Add mb]
With this change, the sequence of operations might be as follows:
\begin{sequence}
-\item CPU~0 executes \co{a = 1}. The corresponding
- cache line is read-only in
- CPU~0's cache, so CPU~0 places the new value of ``a'' in its
- store buffer and transmits an ``invalidate'' message in order
- to flush the corresponding cache line from CPU~1's cache.
+\item CPU~0 executes \co{a = 1}.
+ The corresponding cache line is read-only in CPU~0's cache,
+ so CPU~0 places the new value of ``a'' in its store buffer and
+ transmits an ``invalidate'' message in order to flush the
+ corresponding cache line from CPU~1's cache.
\item CPU~1 executes \co{while (b == 0) continue}, but the cache line
containing ``b'' is not in its cache.
It therefore transmits a ``read'' message.
@@ -1335,15 +1341,17 @@ constraints~\cite{PaulMcKenney2005i,PaulMcKenney2005j}:
its own memory accesses in order?
Why or why not?
}\QuickQuizAnswer{
- No. Consider the case where a thread migrates from one CPU to
+ No.
+ Consider the case where a thread migrates from one CPU to
another, and where the destination CPU perceives the source
- CPU's recent memory operations out of order. To preserve
- user-mode sanity, kernel hackers must use memory barriers in
- the context-switch path. However, the locking already required
- to safely do a context switch should automatically provide
- the memory barriers needed to cause the user-level task to see
- its own accesses in order. That said, if you are designing a
- super-optimized scheduler, either in the kernel or at user level,
+ CPU's recent memory operations out of order.
+ To preserve user-mode sanity, kernel hackers must use memory
+ barriers in the context-switch path.
+ However, the locking already required to safely do a context
+ switch should automatically provide the memory barriers needed
+ to cause the user-level task to see its own accesses in order.
+ That said, if you are designing a super-optimized scheduler,
+ either in the kernel or at user level,
please keep this scenario in mind!
}\QuickQuizEnd
@@ -1422,7 +1430,8 @@ the assertion.
between CPU~1's ``while'' and assignment to ``c''?
Why or why not?
}\QuickQuizAnswer{
- No. Such a memory barrier would only force ordering local to CPU~1.
+ No.
+ Such a memory barrier would only force ordering local to CPU~1.
It would have no effect on the relative ordering of CPU~0's and
CPU~1's accesses, so the assertion could still fail.
However, all mainstream computer systems provide one mechanism
diff --git a/count/count.tex b/count/count.tex
index b89a566c..b69515a1 100644
--- a/count/count.tex
+++ b/count/count.tex
@@ -33,7 +33,7 @@ counting.
}\EQuickQuizEnd
\EQuickQuiz{
- { \bfseries Network-packet counting problem. }
+ {\bfseries Network-packet counting problem.}
Suppose that you need to collect statistics on the number
of networking packets transmitted and received.
Packets might be transmitted or received by any CPU on the system.
@@ -62,7 +62,7 @@ counting.
\QuickQuizLabel{\QcountQstatcnt}
\EQuickQuiz{
- { \bfseries Approximate structure-allocation limit problem. }
+ {\bfseries Approximate structure-allocation limit problem.}
Suppose that you need to maintain a count of the number of
structures allocated in order to fail any allocations
once the number of structures in use exceeds a limit
@@ -84,7 +84,7 @@ counting.
\QuickQuizLabel{\QcountQapproxcnt}
\EQuickQuiz{
- { \bfseries Exact structure-allocation limit problem. }
+ {\bfseries Exact structure-allocation limit problem.}
Suppose that you need to maintain a count of the number of
structures allocated in order to fail any allocations
once the number of structures in use exceeds an exact limit
@@ -111,7 +111,7 @@ counting.
\QuickQuizLabel{\QcountQexactcnt}
\EQuickQuiz{
- { \bfseries Removable I/O device access-count problem. }
+ {\bfseries Removable I/O device access-count problem.}
Suppose that you need to maintain a reference count on a
heavily used removable mass-storage device, so that you
can tell the user when it is safe to remove the device.
@@ -1829,7 +1829,8 @@ with exact limits.
\section{Exact Limit Counters}
\label{sec:count:Exact Limit Counters}
%
-\epigraph{Exactitude can be expensive. Spend wisely.}{\emph{Unknown}}
+\epigraph{Exactitude can be expensive.
+ Spend wisely.}{\emph{Unknown}}
To solve the exact structure-allocation limit problem noted in
\QuickQuizRef{\QcountQexactcnt},
diff --git a/datastruct/datastruct.tex b/datastruct/datastruct.tex
index 26d5c556..6e18fda9 100644
--- a/datastruct/datastruct.tex
+++ b/datastruct/datastruct.tex
@@ -4,8 +4,9 @@
\QuickQuizChapter{chp:Data Structures}{Data Structures}{qqzdatastruct}
%
-\Epigraph{Bad programmers worry about the code. Good programmers worry
- about data structures and their relationships.}
+\Epigraph{Bad programmers worry about the code.
+ Good programmers worry about data structures and their
+ relationships.}
{\emph{Linus Torvalds}}
Serious discussions of algorithms include time complexity of their
@@ -124,9 +125,10 @@ permitting a hash table to access its elements extremely efficiently.
In addition, each bucket has its own lock, so that elements in different
buckets of the hash table may be added, deleted, and looked up completely
-independently. A large hash table with a large number of buckets (and
-thus locks), with each bucket containing a small number of elements
-should therefore provide excellent scalability.
+independently.
+A large hash table with a large number of buckets (and thus locks), with
+each bucket containing a small number of elements should therefore provide
+excellent scalability.
\subsection{Hash-Table Implementation}
\label{sec:datastruct:Hash-Table Implementation}
@@ -1806,7 +1808,8 @@ library~\cite{MathieuDesnoyers2009URCU}.
\section{Other Data Structures}
\label{sec:datastruct:Other Data Structures}
%
-\epigraph{All life is an experiment. The more experiments you make the better.}
+\epigraph{All life is an experiment.
+ The more experiments you make the better.}
{\emph{Ralph Waldo Emerson}}
The preceding sections have focused on data structures that enhance
diff --git a/debugging/debugging.tex b/debugging/debugging.tex
index 9d6e7c36..4c77453d 100644
--- a/debugging/debugging.tex
+++ b/debugging/debugging.tex
@@ -635,7 +635,8 @@ you already have a good test suite.
\section{Tracing}
\label{sec:debugging:Tracing}
%
-\epigraph{The machine knows what is wrong. Make it tell you.}{\emph{Unknown}}
+\epigraph{The machine knows what is wrong.
+ Make it tell you.}{\emph{Unknown}}
When all else fails, add a \co{printk()}!
Or a \co{printf()}, if you are working with user-mode C-language applications.
@@ -2524,9 +2525,9 @@ This script takes three optional arguments as follows:
into, for example, a divisor of four means that the first quarter of
the data elements will be assumed to be good.
This defaults to three.
-\item [\lopt{relerr}\nf{:}] Relative measurement error. The script
- assumes that values that differ by less than this error are for all
- intents and purposes equal.
+\item [\lopt{relerr}\nf{:}] Relative measurement error.
+ The script assumes that values that differ by less than this
+ error are for all intents and purposes equal.
This defaults to 0.01, which is equivalent to 1\,\%.
\item [\lopt{trendbreak}\nf{:}] Ratio of inter-element spacing
constituting a break in the trend of the data.
@@ -2720,7 +2721,8 @@ In short, validation always will require some measure of the behavior of
the system.
To be at all useful, this measure must be a severe summarization of the
system, which in turn means that it can be misleading.
-So as the saying goes, ``Be careful. It is a real world out there.''
+So as the saying goes, ``Be careful.
+It is a real world out there.''
But what if you are working on the Linux kernel, which as of 2017 was
estimated to have more than 20 billion instances running throughout
diff --git a/defer/defer.tex b/defer/defer.tex
index 2d049cfe..3fecc2ac 100644
--- a/defer/defer.tex
+++ b/defer/defer.tex
@@ -7,8 +7,8 @@
\Epigraph{All things come to those who wait.}{\emph{Violet Fane}}
The strategy of deferring work goes back before the dawn of recorded
-history. It has occasionally been derided as procrastination or
-even as sheer laziness.
+history.
+It has occasionally been derided as procrastination or even as sheer laziness.
However, in the last few decades workers have recognized this strategy's value
in simplifying and streamlining parallel algorithms~\cite{Kung80,HMassalinPhD}.
Believe it or not, ``laziness'' in parallel programming often outperforms and
diff --git a/defer/hazptr.tex b/defer/hazptr.tex
index e9264fb7..7c7dd831 100644
--- a/defer/hazptr.tex
+++ b/defer/hazptr.tex
@@ -214,9 +214,10 @@ Otherwise, the element's \co{->iface} field is returned to the caller.
Note that line~\lnref{tryrecord} invokes \co{hp_try_record()} rather
than the easier-to-use \co{hp_record()}, restarting the full search
upon \co{hp_try_record()} failure.
-And such restarting is absolutely required for correctness. To see this,
-consider a hazard-pointer-protected linked list containing elements~A,
-B, and~C that is subjected to the following sequence of events:
+And such restarting is absolutely required for correctness.
+To see this, consider a hazard-pointer-protected linked list
+containing elements~A, B, and~C that is subjected to the following
+sequence of events:
\end{fcvref}
\begin{enumerate}
diff --git a/defer/rcufundamental.tex b/defer/rcufundamental.tex
index 6ff1bd6b..00b80d63 100644
--- a/defer/rcufundamental.tex
+++ b/defer/rcufundamental.tex
@@ -265,8 +265,9 @@ In the figure, \co{P0()}'s access to \co{y} follows \co{P1()}'s access
to this same variable, and thus follows the grace period generated by
\co{P1()}'s call to \co{synchronize_rcu()}.
It is therefore guaranteed that \co{P0()}'s access to \co{x} will follow
-\co{P1()}'s access. In this case, if \co{r2}'s final value is 1, then
-\co{r1}'s final value is guaranteed to also be 1.
+\co{P1()}'s access.
+In this case, if \co{r2}'s final value is 1, then \co{r1}'s final value
+is guaranteed to also be 1.
\QuickQuiz{
What would happen if the order of \co{P0()}'s two accesses was
diff --git a/easy/easy.tex b/easy/easy.tex
index 50a616cc..1ac5b419 100644
--- a/easy/easy.tex
+++ b/easy/easy.tex
@@ -60,7 +60,8 @@ things are covered in the next section.
\label{sec:easy:Rusty Scale for API Design}
%
\epigraph{Finding the appropriate measurement is thus not a mathematical
- exercise. It is a risk-taking judgment.}
+ exercise.
+ It is a risk-taking judgment.}
{\emph{Peter Drucker}}
% http://billhennessy.com/simple-strategies/2015/09/09/i-wish-drucker-never-said-it
% Rusty is OK with this: July 19, 2006.
diff --git a/formal/dyntickrcu.tex b/formal/dyntickrcu.tex
index 98bdaf95..ea534b10 100644
--- a/formal/dyntickrcu.tex
+++ b/formal/dyntickrcu.tex
@@ -731,8 +731,9 @@ for the first condition:
and didn't take any interrupts, NMIs, SMIs, or whatever,
then it cannot be in the middle of an \co{rcu_read_lock()}, so
the next \co{rcu_read_lock()} it executes must use the new value
- of the counter. So we can safely pretend that this CPU
- already acknowledged the counter.
+ of the counter.
+ So we can safely pretend that this CPU already acknowledged
+ the counter.
\end{quote}
The first condition does match this, because if \qco{curr == snap}
@@ -1104,7 +1105,8 @@ states, passing without errors.
\begin{quote}
Debugging is twice as hard as writing the code in the first
- place. Therefore, if you write the code as cleverly as possible,
+ place.
+ Therefore, if you write the code as cleverly as possible,
you are, by definition, not smart enough to debug it.
\end{quote}
@@ -1161,9 +1163,10 @@ This effort provided some lessons (re)learned:
\item {\bf Always verify your verification code.}
The usual way to do this is to insert a deliberate bug
- and verify that the verification code catches it. Of course,
- if the verification code fails to catch this bug, you may also
- need to verify the bug itself, and so on, recursing infinitely.
+ and verify that the verification code catches it.
+ Of course, if the verification code fails to catch this bug,
+ you may also need to verify the bug itself, and so on,
+ recursing infinitely.
However, if you find yourself in this position,
getting a good night's sleep
can be an extremely effective debugging technique.
diff --git a/formal/ppcmem.tex b/formal/ppcmem.tex
index 95be861a..019d0161 100644
--- a/formal/ppcmem.tex
+++ b/formal/ppcmem.tex
@@ -99,30 +99,33 @@ exists @lnlbl[assert:b]
\begin{fcvref}[ln:formal:PPCMEM Litmus Test]
In the example, \clnref{type} identifies the type of system (``ARM'' or
-``PPC'') and contains the title for the model. \Clnref{altname}
-provides a place for an
+``PPC'') and contains the title for the model.
+\Clnref{altname} provides a place for an
alternative name for the test, which you will usually want to leave
-blank as shown in the above example. Comments can be inserted between
+blank as shown in the above example.
+Comments can be inserted between
\clnref{altname,init:b} using the OCaml (or Pascal) syntax of \nbco{(* *)}.
\Clnrefrange{init:b}{init:e} give initial values for all registers;
each is of the form
\co{P:R=V}, where \co{P} is the process identifier, \co{R} is the register
-identifier, and \co{V} is the value. For example, process 0's register
-r3 initially contains the value 2. If the value is a variable (\co{x},
-\co{y}, or \co{z} in the example) then the register is initialized to the
-address of the variable. It is also possible to initialize the contents
-of variables, for example, \co{x=1} initializes the value of \co{x} to
-1. Uninitialized variables default to the value zero, so that in the
+identifier, and \co{V} is the value.
+For example, process 0's register r3 initially contains the value~2.
+If the value is a variable (\co{x}, \co{y}, or \co{z} in the example)
+then the register is initialized to the address of the variable.
+It is also possible to initialize the contents of variables, for example,
+\co{x=1} initializes the value of \co{x} to~1.
+Uninitialized variables default to the value zero, so that in the
example, \co{x}, \co{y}, and \co{z} are all initially zero.
\Clnref{procid} provides identifiers for the two processes, so that
the \co{0:r3=2} on \clnref{init:0} could instead have been written
-\co{P0:r3=2}. \Clnref{procid} is
-required, and the identifiers must be of the form \co{Pn}, where \co{n}
-is the column number, starting from zero for the left-most column. This
-may seem unnecessarily strict, but it does prevent considerable confusion
-in actual use.
+\co{P0:r3=2}.
+\Clnref{procid} is required, and the identifiers must be of the form
+\co{Pn}, where \co{n} is the column number, starting from zero for
+the left-most column.
+This may seem unnecessarily strict, but it does prevent considerable
+confusion in actual use.
\end{fcvref}
\QuickQuiz{
@@ -149,23 +152,23 @@ A given process can have empty lines, as is the case for P0's
\clnref{P0empty} and P1's \clnrefrange{P1empty:b}{P1empty:e}.
Labels and branches are permitted, as demonstrated by the branch
on \clnref{P0bne} to the label on \clnref{P0fail1}.
-That said, too-free use of branches
-will expand the state space. Use of loops is a particularly good way to
-explode your state space.
+That said, too-free use of branches will expand the state space.
+Use of loops is a particularly good way to explode your state space.
\Clnrefrange{assert:b}{assert:e} show the assertion, which in this case
-indicates that we
-are interested in whether P0's and P1's r3 registers can both contain
-zero after both threads complete execution. This assertion is important
-because there are a number of use cases that would fail miserably if
-both P0 and P1 saw zero in their respective r3 registers.
-
-This should give you enough information to construct simple litmus
-tests. Some additional documentation is available, though much of this
+indicates that we are interested in whether P0's and P1's r3 registers
+can both contain zero after both threads complete execution.
+This assertion is important because there are a number of use cases
+that would fail miserably if both P0 and P1 saw zero in their
+respective r3 registers.
+
+This should give you enough information to construct simple litmus tests.
+Some additional documentation is available, though much of this
additional documentation is intended for a different research tool that
-runs tests on actual hardware. Perhaps more importantly, a large number of
-pre-existing litmus tests are available with the online tool (available
-via the ``Select ARM Test'' and ``Select POWER Test'' buttons at
+runs tests on actual hardware.
+Perhaps more importantly, a large number of pre-existing litmus tests
+are available with the online tool (available via the ``Select ARM Test''
+and ``Select POWER Test'' buttons at
\url{https://www.cl.cam.ac.uk/~pes20/ppcmem/}).
It is quite likely that one of these pre-existing litmus tests will
answer your Power or \ARM\ memory-ordering question.
@@ -175,17 +178,18 @@ answer your Power or \ARM\ memory-ordering question.
P0's \clnref{reginit,stw} are equivalent to the C statement \co{x=1}
because \clnref{init:0} defines P0's register \co{r2} to be the address
-of \co{x}. P0's \clnref{P0lwarx,P0stwcx} are the mnemonics for
-load-linked (``load register
-exclusive'' in \ARM\ parlance and ``load reserve'' in Power parlance)
-and store-conditional (``store register exclusive'' in \ARM\ parlance),
-respectively. When these are used together, they form an atomic
-instruction sequence, roughly similar to the \IXacrml{cas} sequences
-exemplified by the x86 \co{lock;cmpxchg} instruction. Moving to a higher
-level of abstraction, the sequence from \clnrefrange{P0lwsync}{P0isync}
+of~\co{x}.
+P0's \clnref{P0lwarx,P0stwcx} are the mnemonics for load-linked
+(``load register exclusive'' in \ARM\ parlance and ``load reserve''
+in Power parlance) and store-conditional (``store register exclusive''
+in \ARM\ parlance), respectively.
+When these are used together, they form an atomic instruction sequence,
+roughly similar to the \IXacrml{cas} sequences exemplified by the
+x86 \co{lock;cmpxchg} instruction.
+Moving to a higher level of abstraction, the sequence from
+\clnrefrange{P0lwsync}{P0isync}
is equivalent to the Linux kernel's \co{atomic_add_return(&z, 0)}.
-Finally, \clnref{P0lwz} is
-roughly equivalent to the C statement \co{r3=y}.
+Finally, \clnref{P0lwz} is roughly equivalent to the C statement \co{r3=y}.
P1's \clnref{reginit,stw} are equivalent to the C statement \co{y=1},
\clnref{P1sync}
@@ -203,11 +207,11 @@ and \clnref{P1lwz} is equivalent to the C statement \co{r3=x}.
The implementation of powerpc version of \co{atomic_add_return()}
loops when the \co{stwcx} instruction fails, which it communicates
by setting non-zero status in the condition-code register,
- which in turn is tested by the \co{bne} instruction. Because actually
- modeling the loop would result in state-space explosion, we
- instead branch to the Fail: label, terminating the model with
- the initial value of 2 in P0's \co{r3} register, which
- will not trigger the exists assertion.
+ which in turn is tested by the \co{bne} instruction.
+ Because actually modeling the loop would result in state-space
+ explosion, we instead branch to the \co{Fail:} label,
+ terminating the model with the initial value of~2 in P0's \co{r3}
+ register, which will not trigger the exists assertion.
There is some debate about whether this trick is universally
applicable, but I have not seen an example where it fails.
@@ -369,38 +373,42 @@ cannot happen.
\label{sec:formal:PPCMEM Discussion}
These tools promise to be of great help to people working on low-level
-parallel primitives that run on \ARM\ and on Power. These tools do have
-some intrinsic limitations:
+parallel primitives that run on \ARM\ and on Power.
+These tools do have some intrinsic limitations:
\begin{enumerate}
\item These tools are research prototypes, and as such are unsupported.
\item These tools do not constitute official statements by IBM or \ARM\
- on their respective CPU architectures. For example, both
- corporations reserve the right to report a bug at any time against
- any version of any of these tools. These tools are therefore not a
- substitute for careful stress testing on real hardware. Moreover,
- both the tools and the model that they are based on are under
- active development and might change at any time. On the other
- hand, this model was developed in consultation with the relevant
- hardware experts, so there is good reason to be confident that
- it is a robust representation of the architectures.
+ on their respective CPU architectures.
+ For example, both corporations reserve the right to report a bug
+ at any time against any version of any of these tools.
+ These tools are therefore not a substitute for careful stress
+ testing on real hardware.
+ Moreover, both the tools and the model that they are based on
+ are under active development and might change at any time.
+ On the other hand, this model was developed in consultation
+ with the relevant hardware experts, so there is good reason to be
+ confident that it is a robust representation of the architectures.
\item These tools currently handle a subset of the instruction set.
This subset has been sufficient for my purposes, but your mileage
- may vary. In particular, the tool handles only word-sized accesses
- (32 bits), and the words accessed must be properly aligned.\footnote{
+ may vary.
+ In particular, the tool handles only word-sized accesses (32 bits),
+ and the words accessed must be properly aligned.\footnote{
But recent work focuses on mixed-size
accesses~\cite{Flur:2017:MCA:3093333.3009839}.}
In addition, the tool does not handle some of the weaker variants
of the \ARM\ memory-barrier instructions, nor does it handle
arithmetic.
\item The tools are restricted to small loop-free code fragments
- running on small numbers of threads. Larger examples result
+ running on small numbers of threads.
+ Larger examples result
in state-space explosion, just as with similar tools such as
Promela and spin.
\item The full state-space search does not give any indication of how
- each offending state was reached. That said, once you realize
- that the state is in fact reachable, it is usually not too hard
- to find that state using the interactive tool.
+ each offending state was reached.
+ That said, once you realize that the state is in fact reachable,
+ it is usually not too hard to find that state using the
+ interactive tool.
\item These tools are not much good for complex data structures, although
it is possible to create and traverse extremely simple linked
lists using initialization statements of the form
@@ -409,42 +417,46 @@ some intrinsic limitations:
Of course, handling such things would require that they be
formalized, which does not appear to be in the offing.
\item The tools will detect only those problems for which you code an
- assertion. This weakness is common to all formal methods, and
- is yet another reason why testing remains important. In the
- immortal words of Donald Knuth quoted at the beginning of this
- chapter, ``Beware of bugs in the above
- code; I have only proved it correct, not tried it.''
+ assertion.
+ This weakness is common to all formal methods, and is yet another
+ reason why testing remains important.
+ In the immortal words of Donald Knuth quoted at the beginning of
+ this chapter, ``Beware of bugs in the above code;
+ I have only proved it correct, not tried it.''
\end{enumerate}
That said, one strength of these tools is that they are designed to
model the full range of behaviors allowed by the architectures, including
behaviors that are legal, but which current hardware implementations do
-not yet inflict on unwary software developers. Therefore, an algorithm
-that is vetted by these tools likely has some additional safety margin
-when running on real hardware. Furthermore, testing on real hardware can
-only find bugs; such testing is inherently incapable of proving a given
-usage correct. To appreciate this, consider that the researchers
-routinely ran in excess of 100 billion test runs on real hardware to
-validate their model.
+not yet inflict on unwary software developers.
+Therefore, an algorithm that is vetted by these tools likely has some
+additional safety margin when running on real hardware.
+Furthermore, testing on real hardware can only find bugs; such testing
+is inherently incapable of proving a given usage correct.
+To appreciate this, consider that the researchers routinely ran in excess
+of 100 billion test runs on real hardware to validate their model.
In one case, behavior that is allowed by the architecture did not occur,
despite 176 billion runs~\cite{JadeAlglave2011ppcmem}.
In contrast, the
full-state-space search allows the tool to prove code fragments correct.
It is worth repeating that formal methods and tools are no substitute for
-testing. The fact is that producing large reliable concurrent software
-artifacts, the Linux kernel for example, is quite difficult. Developers
-must therefore be prepared to apply every tool at their disposal towards
-this goal. The tools presented in this chapter are able to locate bugs that
-are quite difficult to produce (let alone track down) via testing. On the
-other hand, testing can be applied to far larger bodies of software than
-the tools presented in this chapter are ever likely to handle. As always,
-use the right tools for the job!
+testing.
+The fact is that producing large reliable concurrent software artifacts,
+the Linux kernel for example, is quite difficult.
+Developers must therefore be prepared to apply every tool at their
+disposal towards this goal.
+The tools presented in this chapter are able to locate bugs that are
+quite difficult to produce (let alone track down) via testing.
+On the other hand, testing can be applied to far larger bodies of software
+than the tools presented in this chapter are ever likely to handle.
+As always, use the right tools for the job!
Of course, it is always best to avoid the need to work at this level
by designing your parallel code to be easily partitioned and then
using higher-level primitives (such as locks, sequence counters, atomic
-operations, and RCU) to get your job done more straightforwardly. And even
-if you absolutely must use low-level memory barriers and read-modify-write
-instructions to get your job done, the more conservative your use of
-these sharp instruments, the easier your life is likely to be.
+operations, and RCU) to get your job done more straightforwardly.
+And even if you absolutely must use low-level memory barriers and
+read-modify-write instructions to get your job done, the more
+conservative your use of these sharp instruments, the easier your life
+is likely to be.
diff --git a/formal/spinhint.tex b/formal/spinhint.tex
index 305a7014..d05bab16 100644
--- a/formal/spinhint.tex
+++ b/formal/spinhint.tex
@@ -244,12 +244,13 @@ Given a source file \path{qrcu.spin}, one can use the following commands:
\item [\tco{spin -a qrcu.spin}]
Create a file \path{pan.c} that fully searches the state machine.
\item [\tco{cc -DSAFETY [-DCOLLAPSE] [-DMA=N] -o pan pan.c}]
- Compile the generated state-machine search. The \co{-DSAFETY}
- generates optimizations that are appropriate if you have only
- assertions (and perhaps \co{never} statements). If you have
- liveness, fairness, or forward-progress checks, you may need
- to compile without \co{-DSAFETY}. If you leave off \co{-DSAFETY}
- when you could have used it, the program will let you know.
+ Compile the generated state-machine search.
+ The \co{-DSAFETY} generates optimizations that are appropriate
+ if you have only assertions (and perhaps \co{never} statements).
+ If you have liveness, fairness, or forward-progress checks,
+ you may need to compile without \co{-DSAFETY}.
+ If you leave off \co{-DSAFETY} when you could have used it,
+ the program will let you know.
The optimizations produced by \co{-DSAFETY} greatly speed things
up, so you should use it when you can.
@@ -263,9 +264,10 @@ Given a source file \path{qrcu.spin}, one can use the following commands:
Another optional flag \co{-DMA=N} generates code for a slow
but aggressive state-space memory compression mode.
\item [\tco{./pan [-mN] [-wN]}]
- This actually searches the state space. The number of states
- can reach into the tens of millions with very small state
- machines, so you will need a machine with large memory.
+ This actually searches the state space.
+ The number of states can reach into the tens of millions with
+ very small state machines, so you will need a machine with
+ large memory.
For example, \path{qrcu.spin} with 3~updaters and 2~readers required
10.5\,GB of memory even with the \co{-DCOLLAPSE} flag.
@@ -276,23 +278,23 @@ Given a source file \path{qrcu.spin}, one can use the following commands:
The \co{-wN} option specifies the hashtable size.
The default for full state-space search is \co{-w24}.\footnote{
- As of Spin Version 6.4.6 and 6.4.8. In the online manual of
- Spin dated 10 July 2011, the default for exhaustive search
- mode is said to be \co{-w19}, which does not meet
- the actual behavior.}
+ As of Spin Version 6.4.6 and 6.4.8.
+ In the online manual of Spin dated 10 July 2011, the
+ default for exhaustive search mode is said to be \co{-w19},
+ which does not meet the actual behavior.}
If you aren't sure whether your machine has enough memory,
- run \co{top} in one window and \co{./pan} in another. Keep the
- focus on the \co{./pan} window so that you can quickly kill
- execution if need be. As soon as CPU time drops much below
- 100\,\%, kill \co{./pan}. If you have removed focus from the
- window running \co{./pan}, you may wait a long time for the
- windowing system to grab enough memory to do anything for
- you.
+ run \co{top} in one window and \co{./pan} in another.
+ Keep the focus on the \co{./pan} window so that you can quickly
+ kill execution if need be.
+ As soon as CPU time drops much below 100\,\%, kill \co{./pan}.
+ If you have removed focus from the window running \co{./pan},
+ you may wait a long time for the windowing system to grab
+ enough memory to do anything for you.
Another option to avoid memory exhaustion is the
- \co{-DMEMLIM=N} compiler flag. \co{-DMEMLIM=2000}
- would set the maximum of 2\,GB.
+ \co{-DMEMLIM=N} compiler flag.
+ \co{-DMEMLIM=2000} would set the maximum of 2\,GB.
Don't forget to capture the output, especially
if you are working on a remote machine.
@@ -320,7 +322,8 @@ Promela will provide some surprises to people used to coding in C,
C++, or Java.
\begin{enumerate}
-\item In C, ``\co{;}'' terminates statements. In Promela it separates them.
+\item In C, ``\co{;}'' terminates statements.
+ In Promela it separates them.
Fortunately, more recent versions of Spin have become
much more forgiving of ``extra'' semicolons.
\item Promela's looping construct, the \co{do} statement, takes
@@ -328,44 +331,52 @@ C++, or Java.
This \co{do} statement closely resembles a looping if-then-else
statement.
\item In C's \co{switch} statement, if there is no matching case, the whole
- statement is skipped. In Promela's equivalent, confusingly called
- \co{if}, if there is no matching guard expression, you get an error
- without a recognizable corresponding error message.
+ statement is skipped.
+ In Promela's equivalent, confusingly called \co{if}, if there is
+ no matching guard expression, you get an error without a
+ recognizable corresponding error message.
So, if the error output indicates an innocent line of code,
check to see if you left out a condition from an \co{if} or \co{do}
statement.
\item When creating stress tests in C, one usually races suspect operations
- against each other repeatedly. In Promela, one instead sets up
- a single race, because Promela will search out all the possible
- outcomes from that single race. Sometimes you do need to loop
- in Promela, for example, if multiple operations overlap, but
+ against each other repeatedly.
+ In Promela, one instead sets up a single race, because Promela
+ will search out all the possible outcomes from that single race.
+ Sometimes you do need to loop in Promela, for example,
+ if multiple operations overlap, but
doing so greatly increases the size of your state space.
\item In C, the easiest thing to do is to maintain a loop counter to track
- progress and terminate the loop. In Promela, loop counters
- must be avoided like the plague because they cause the state
- space to explode. On the other hand, there is no penalty for
- infinite loops in Promela as long as none of the variables
- monotonically increase or decrease---Promela will figure out
- how many passes through the loop really matter, and automatically
- prune execution beyond that point.
+ progress and terminate the loop.
+ In Promela, loop counters must be avoided like the plague
+ because they cause the state space to explode.
+ On the other hand, there is no penalty for infinite loops in
+ Promela as long as none of the variables monotonically increase
+ or decrease---Promela will figure out how many passes through
+ the loop really matter, and automatically prune execution beyond
+ that point.
\item In C torture-test code, it is often wise to keep per-task control
- variables. They are cheap to read, and greatly aid in debugging the
- test code. In Promela, per-task control variables should be used
- only when there is no other alternative. To see this, consider
- a 5-task verification with one bit each to indicate completion.
- This gives 32 states. In contrast, a simple counter would have
- only six states, more than a five-fold reduction. That factor
- of five might not seem like a problem, at least not until you
- are struggling with a verification program possessing more than
- 150 million states consuming more than 10\,GB of memory!
+ variables.
+ They are cheap to read, and greatly aid in debugging the test code.
+ In Promela, per-task control variables should be used only when
+ there is no other alternative.
+ To see this, consider a 5-task verification with one bit each
+ to indicate completion.
+ This gives 32 states.
+ In contrast, a simple counter would have only six states,
+ more than a five-fold reduction.
+ That factor of five might not seem like a problem, at least
+ not until you are struggling with a verification program
+ possessing more than 150 million states consuming more
+ than 10\,GB of memory!
\item One of the most challenging things both in C torture-test code and
- in Promela is formulating good assertions. Promela also allows
- \co{never} claims that act like an assertion replicated
- between every line of code.
+ in Promela is formulating good assertions.
+ Promela also allows \co{never} claims that act like an assertion
+ replicated between every line of code.
\item Dividing and conquering is extremely helpful in Promela in keeping
- the state space under control. Splitting a large model into two
- roughly equal halves will result in the state space of each
- half being roughly the square root of the whole.
+ the state space under control.
+ Splitting a large model into two roughly equal halves will result
+ in the state space of each half being roughly the square root of
+ the whole.
For example, a million-state combined model might reduce to a
pair of thousand-state models.
Not only will Promela handle the two smaller models much more
@@ -382,10 +393,11 @@ is a bit abusive.
The following tricks can help you to abuse Promela safely:
\begin{enumerate}
-\item Memory reordering. Suppose you have a pair of statements
- copying globals x and y to locals r1 and r2, where ordering
- matters (e.g., unprotected by locks), but where you have
- no memory barriers. This can be modeled in Promela as follows:
+\item Memory reordering.
+ Suppose you have a pair of statements copying globals x and y
+ to locals r1 and r2, where ordering matters
+ (e.g., unprotected by locks), but where you have no memory barriers.
+ This can be modeled in Promela as follows:
\begin{VerbatimN}[samepage=true]
if
@@ -405,10 +417,11 @@ fi
if used too heavily.
In addition, it requires you to anticipate possible reorderings.
-\item State reduction. If you have complex assertions, evaluate
- them under \co{atomic}. After all, they are not part of the
- algorithm. One example of a complex assertion (to be discussed
- in more detail later) is as shown in
+\item State reduction.
+ If you have complex assertions, evaluate them under \co{atomic}.
+ After all, they are not part of the algorithm.
+ One example of a complex assertion (to be discussed in more
+ detail later) is as shown in
Listing~\ref{lst:formal:Complex Promela Assertion}.
There is no reason to evaluate this assertion
@@ -588,9 +601,9 @@ As expected, this run has no assertion failures (``errors: 0'').
\item The declaration of \co{sum} should be moved to within
the init block, since it is not used anywhere else.
\item The assertion code should be moved outside of the
- initialization loop. The initialization loop can
- then be placed in an atomic block, greatly reducing
- the state space (by how much?).
+ initialization loop.
+ The initialization loop can then be placed in an atomic
+ block, greatly reducing the state space (by how much?).
\item The atomic block covering the assertion code should
be extended to include the initialization of \co{sum}
and \co{j}, and also to cover the assertion.
@@ -787,7 +800,8 @@ this update still be in progress.
\end{fcvref}
}\QuickQuizAnswerB{
Because those operations are for the benefit of the
- assertion only. They are not part of the algorithm itself.
+ assertion only.
+ They are not part of the algorithm itself.
There is therefore no harm in marking them atomic, and
so marking them greatly reduces the state space that must
be searched by the Promela model.
@@ -800,7 +814,8 @@ this update still be in progress.
\emph{really} necessary?
\end{fcvref}
}\QuickQuizAnswerE{
- Yes. To see this, delete these lines and run the model.
+ Yes.
+ To see this, delete these lines and run the model.
Alternatively, consider the following sequence of steps:
@@ -810,7 +825,8 @@ this update still be in progress.
the value of \co{ctr[1]} is two.
\item An updater starts executing, and sees that the sum of
the counters is two so that the fastpath cannot be
- executed. It therefore acquires the lock.
+ executed.
+ It therefore acquires the lock.
\item A second updater starts executing, and fetches the value
of \co{ctr[0]}, which is zero.
\item The first updater adds one to \co{ctr[0]}, flips
diff --git a/glossary.tex b/glossary.tex
index 98a27438..e8d93c90 100644
--- a/glossary.tex
+++ b/glossary.tex
@@ -284,10 +284,11 @@
set of critical sections guarded by that lock, while a
``reader-writer lock'' permits any number of reading
threads, or but one writing thread, into the set of critical
- sections guarded by that lock. (Just to be clear, the presence
- of a writer thread in any of a given reader-writer lock's
- critical sections will prevent any reader from entering
- any of that lock's critical sections and vice versa.)
+ sections guarded by that lock.
+ (Just to be clear, the presence of a writer thread in any of
+ a given reader-writer lock's critical sections will prevent
+ any reader from entering any of that lock's critical sections
+ and vice versa.)
\item[\IX{Lock Contention}:]
A lock is said to be suffering contention when it is being
used so heavily that there is often a CPU waiting on it.
diff --git a/intro/intro.tex b/intro/intro.tex
index 4f38f376..812b34fd 100644
--- a/intro/intro.tex
+++ b/intro/intro.tex
@@ -572,7 +572,8 @@ programming environments:
Its productivity is believed by many to be even lower than that
of C/C++ ``locking plus threads'' environments.
\item[OpenMP:] This set of compiler directives can be used
- to parallelize loops. It is thus quite specific to this
+ to parallelize loops.
+ It is thus quite specific to this
task, and this specificity often limits its performance.
It is, however, much easier to use than MPI or C/C++
``locking plus threads.''
@@ -834,17 +835,21 @@ reduce the amount of data that must be read.
}\QuickQuizAnswer{
There are any number of potential bottlenecks:
\begin{enumerate}
- \item Main memory. If a single thread consumes all available
+ \item Main memory.
+ If a single thread consumes all available
memory, additional threads will simply page themselves
silly.
- \item Cache. If a single thread's cache footprint completely
+ \item Cache.
+ If a single thread's cache footprint completely
fills any shared CPU cache(s), then adding more threads
will simply thrash those affected caches, as will be
seen in \cref{chp:Data Structures}.
- \item Memory bandwidth. If a single thread consumes all available
+ \item Memory bandwidth.
+ If a single thread consumes all available
memory bandwidth, additional threads will simply
result in additional queuing on the system interconnect.
- \item I/O bandwidth. If a single thread is I/O bound,
+ \item I/O bandwidth.
+ If a single thread is I/O bound,
adding more threads will simply result in them all
waiting in line for the affected I/O resource.
\end{enumerate}
@@ -960,11 +965,13 @@ overlap computation and I/O so as to fully utilize I/O devices.
There are any number of potential limits on the number of
threads:
\begin{enumerate}
- \item Main memory. Each thread consumes some memory
+ \item Main memory.
+ Each thread consumes some memory
(for its stack if nothing else), so that excessive
numbers of threads can exhaust memory, resulting
in excessive paging or memory-allocation failures.
- \item I/O bandwidth. If each thread initiates a given
+ \item I/O bandwidth.
+ If each thread initiates a given
amount of mass-storage I/O or networking traffic,
excessive numbers of threads can result in excessive
I/O queuing delays, again degrading performance.
@@ -1239,8 +1246,10 @@ monograph~\cite{AndrewDBirrell1989Threads} is especially telling:
\begin{quote}
Writing concurrent programs has a reputation for being exotic
- and difficult. I~believe it is neither. You need a system
- that provides you with good primitives and suitable libraries,
+ and difficult.
+ I~believe it is neither.
+ You need a system that provides you with good primitives
+ and suitable libraries,
you need a basic caution and carefulness, you need an armory of
useful techniques, and you need to know of the common pitfalls.
I~hope that this paper has helped you towards sharing my belief.
diff --git a/legal.tex b/legal.tex
index 1dd6c6bb..f443df37 100644
--- a/legal.tex
+++ b/legal.tex
@@ -31,10 +31,11 @@ States license.\footnote{
\url{https://creativecommons.org/licenses/by-sa/3.0/us/}}
In brief, you may use the contents of this document for any purpose,
personal, commercial, or otherwise, so long as attribution to the
-authors is maintained. Likewise, the document may be modified,
-and derivative works and translations made available, so long as
-such modifications and derivations are offered to the public on equal
-terms as the non-source-code text and images in the original document.
+authors is maintained.
+Likewise, the document may be modified, and derivative works and
+translations made available, so long as such modifications and
+derivations are offered to the public on equal terms as the
+non-source-code text and images in the original document.
Source code is covered by various versions of the GPL\@.\footnote{
\url{https://www.gnu.org/licenses/gpl-2.0.html}}
diff --git a/locking/locking.tex b/locking/locking.tex
index 6bc93e49..406c5034 100644
--- a/locking/locking.tex
+++ b/locking/locking.tex
@@ -1710,7 +1710,8 @@ be required for the foreseeable future.
\label{sec:locking:Locking Implementation Issues}
%
\epigraph{When you translate a dream into reality, it's never a full
- implementation. It is easier to dream than to do.}
+ implementation.
+ It is easier to dream than to do.}
{\emph{Shai Agassi}}
Developers are almost always best-served by using whatever locking
diff --git a/memorder/memorder.tex b/memorder/memorder.tex
index 397fb101..8c9be547 100644
--- a/memorder/memorder.tex
+++ b/memorder/memorder.tex
@@ -2136,7 +2136,8 @@ page~\pageref{fig:memorder:A Variable With More Simultaneous Values}.
(\path{C-2+2W+o-o+o-o.litmus}).
}\QuickQuizEnd
-But sometimes time really is on our side. Read on!
+But sometimes time really is on our side.
+Read on!
\subsubsection{Happens-Before}
\label{sec:memorder:Happens-Before}
@@ -3158,8 +3159,9 @@ The following list of rules summarizes the lessons of this section:
\end{enumerate}
Again, many popular languages were designed with single-threaded use
-in mind. Successful multithreaded use of these languages requires you
-to pay special attention to your memory references and dependencies.
+in mind.
+Successful multithreaded use of these languages requires you to pay
+special attention to your memory references and dependencies.
\section{Higher-Level Primitives}
\label{sec:memorder:Higher-Level Primitives}
@@ -3868,8 +3870,8 @@ can make portability a challenge, as indicated by
In fact, some software environments simply prohibit
direct use of memory-ordering operations, restricting the programmer
to mutual-exclusion primitives that incorporate them to the extent that
-they are required. Please note that this section is not intended to be
-a reference manual
+they are required.
+Please note that this section is not intended to be a reference manual
covering all (or even most) aspects of each CPU family, but rather
a high-level overview providing a rough comparison.
For full details, see the reference manual for the CPU of interest.
diff --git a/owned/owned.tex b/owned/owned.tex
index aa4c0901..df2a1cce 100644
--- a/owned/owned.tex
+++ b/owned/owned.tex
@@ -4,7 +4,10 @@
\QuickQuizChapter{chp:Data Ownership}{Data Ownership}{qqzowned}
%
-\Epigraph{It is mine, I tell you. My own. My precious. Yes, my precious.}
+\Epigraph{It is mine, I tell you.
+ My own.
+ My precious.
+ Yes, my precious.}
{\emph{Gollum in ``The Fellowship of the Ring'', J.R.R.~Tolkien}}
One of the simplest ways to avoid the synchronization overhead that
diff --git a/together/refcnt.tex b/together/refcnt.tex
index 57a1754e..ae8644e4 100644
--- a/together/refcnt.tex
+++ b/together/refcnt.tex
@@ -5,8 +5,8 @@
\section{Refurbish Reference Counting}
\label{sec:together:Refurbish Reference Counting}
%
-\epigraph{Counting is the religion of this generation. It is its
- hope and its salvation.}
+\epigraph{Counting is the religion of this generation.
+ It is its hope and its salvation.}
{\emph{Gertrude Stein}}
Although reference counting is a conceptually simple technique,
diff --git a/toolsoftrade/toolsoftrade.tex b/toolsoftrade/toolsoftrade.tex
index 77a3790d..b358c22d 100644
--- a/toolsoftrade/toolsoftrade.tex
+++ b/toolsoftrade/toolsoftrade.tex
@@ -289,7 +289,8 @@ in which the child sets a global variable \co{x} to 1 on line~\lnref{setx},
prints a message on line~\lnref{print:c}, and exits on line~\lnref{exit:s}.
The parent continues at line~\lnref{waitall}, where it waits on the child,
and on line~\lnref{print:p} finds that its copy of the variable \co{x} is
-still zero. The output is thus as follows:
+still zero.
+The output is thus as follows:
\end{fcvref}
\begin{VerbatimU}
--
2.17.1
^ permalink raw reply related [flat|nested] 15+ messages in thread* [PATCH -perfbook v2 7/9] styleguide: Make end-of-sentence periods be at the end of lines
2021-04-27 15:18 [PATCH -perfbook v2 0/9] Add script to check period spacing Akira Yokosawa
` (5 preceding siblings ...)
2021-04-27 15:29 ` [PATCH -perfbook v2 6/9] treewide: Make end-of-sentence periods be at end of lines Akira Yokosawa
@ 2021-04-27 15:30 ` Akira Yokosawa
2021-04-27 15:31 ` [PATCH -perfbook v2 8/9] treewide: Fix space in front of \cite{} Akira Yokosawa
` (2 subsequent siblings)
9 siblings, 0 replies; 15+ messages in thread
From: Akira Yokosawa @ 2021-04-27 15:30 UTC (permalink / raw)
To: Paul E. McKenney; +Cc: perfbook, Akira Yokosawa
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
appendix/styleguide/styleguide.tex | 237 ++++++++++++++++-------------
1 file changed, 130 insertions(+), 107 deletions(-)
diff --git a/appendix/styleguide/styleguide.tex b/appendix/styleguide/styleguide.tex
index 407d0c52..7860ee2d 100644
--- a/appendix/styleguide/styleguide.tex
+++ b/appendix/styleguide/styleguide.tex
@@ -8,8 +8,8 @@
\Epigraph{De gustibus non est disputandum.}{\emph{Latin maxim}}
This appendix is a collection of style guides which is intended
-as a reference to improve consistency in perfbook. It also contains
-several suggestions and their experimental examples.
+as a reference to improve consistency in perfbook.
+It also contains several suggestions and their experimental examples.
\Cref{sec:app:styleguide:Paul's Conventions} describes basic
punctuation and spelling rules.
@@ -40,16 +40,18 @@ answers to Akira's questions regarding perfbook's punctuation policy.
\end{quote}
\item American English spelling: ``color'' rather than ``colour''.
\item Oxford comma: ``a, b, and~c'' rather than ``a, b and~c''.
- This is arbitrary. Cases where the Oxford comma results in ambiguity
- should be reworded, for example, by introducing numbering: ``a,
- b, and c and~d'' should be ``(1)~a, (2)~b, and (3)~c and~d''.
-\item Italic for emphasis. Use sparingly.
+ This is arbitrary.
+ Cases where the Oxford comma results in ambiguity should be reworded,
+ for example, by introducing numbering: ``a, b, and c and~d'' should
+ be ``(1)~a, (2)~b, and (3)~c and~d''.
+\item Italic for emphasis.
+ Use sparingly.
\item \verb|\co{}| for identifiers, \verb|\url{}| for URLs,
\verb|\path{}| for filenames.
-\item Dates should use an unambiguous format. Never ``mm/dd/yy''
- or ``dd/mm/yy'', but rather ``July 26, 2016'' or ``26 July 2016''
- or ``26-Jul-2016'' or ``2016/07/26''. I tend to use
- \path{yyyy.mm.ddA} for filenames, for example.
+\item Dates should use an unambiguous format.
+ Never ``mm/dd/yy'' or ``dd/mm/yy'', but rather ``July 26, 2016''
+ or ``26 July 2016'' or ``26-Jul-2016'' or ``2016/07/26''.
+ I tend to use \path{yyyy.mm.ddA} for filenames, for example.
\item North American rules on periods and abbreviations.
For example neither of the following can reasonably be interpreted
as two sentences:
@@ -74,8 +76,8 @@ answers to Akira's questions regarding perfbook's punctuation policy.
\end{quote}
\item I don't like ampersand (``\&'') in headings, but will sometimes
use it if doing so prevents a line break in that heading.
-\item When mentioning words, I use quotations. When introducing
- a new word, I use \verb|\emph{}|.
+\item When mentioning words, I use quotations.
+ When introducing a new word, I use \verb|\emph{}|.
\end{itemize}
Following is a convention regarding punctuation in \LaTeX\ sources.
@@ -106,15 +108,15 @@ states the following rules (rephrased for perfbook).
are used behind numerical values, narrow spaces should be placed between
the values and the symbols.
-A narrow space can be coded in \LaTeX{} by the sequence of
-\qco{\\,}.
+A narrow space can be coded in \LaTeX{} by the sequence of \qco{\\,}.
For example,
\begin{quote}
``2.4\,GHz'', rather then ``2.4GHz''.
\end{quote}
\item Even when the value is used in adjectival sense, a narrow space
-should be placed. For example,
+ should be placed.
+ For example,
\begin{quote}
``a~10\,ms interval'', rather than ``a~10\=/ms interval'' nor
``a~10ms interval''.
@@ -123,15 +125,17 @@ should be placed. For example,
The symbol of micro (\micro :$10^{-6}$) can be typeset easily by
the help of ``gensymb'' \LaTeX\ package.
-A macro \qco{\\micro} can be used in both text and
-math modes. To typeset the symbol of ``microsecond'', you can do
-so by \qco{\\micro s}. For example,
+A macro \qco{\\micro} can be used in both text and math modes.
+To typeset the symbol of ``microsecond'', you can do
+so by \qco{\\micro s}.
+For example,
\begin{quote}
10\,\micro s
\end{quote}
Note that math mode \qco{\\mu} is italic by default and should not
-be used as a prefix. An improper example:
+be used as a prefix.
+An improper example:
\begin{quote}
10\,$\mu $s (math mode \qco{\\mu})
\end{quote}
@@ -161,8 +165,9 @@ An acceptable example:
\end{quote}
Also, it is acceptable to use just ``K'', ``M'', or ``G'' as abbreviations
-appended to a numerical value, e.g., ``4K~entries''. In such cases, no space
-before an abbreviation is required. For example,
+appended to a numerical value, e.g., ``4K~entries''.
+In such cases, no space before an abbreviation is required.
+For example,
\begin{quote}
``8K entries'', rather than ``8\,K entries''.
@@ -172,14 +177,15 @@ If you put a space in between, the symbol looks like a unit symbol and
is confusing.
Note that ``K'' and ``k'' represent $2^{10}$ and $10^3$, respectively.
``M'' can represent either $2^{20}$ or $10^6$, and ``G'' can represent
-either $2^{30}$ or $10^9$. These ambiguities should not be confusing
-in discussing approximate order.
+either $2^{30}$ or $10^9$.
+These ambiguities should not be confusing in discussing approximate order.
\subsubsection{Degree Symbol}
\label{sec:app:styleguide:Degree Symbol}
The angular-degree symbol (\degree) does not require any space in front
-of it. NIST style guide clearly states so.
+of it.
+NIST style guide clearly states so.
The symbol of degree can also be typeset easily by the help of gensymb
package.
@@ -209,10 +215,11 @@ Quote from NIST check list:\footnote{
}
\begin{quote}
- Variables and quantity symbols are in italic type. Unit symbols
- are in roman type. Numbers should generally be written in roman
- type. These rules apply irrespective of the typeface used in
- the surrounding text.
+ Variables and quantity symbols are in italic type.
+ Unit symbols are in roman type.
+ Numbers should generally be written in roman type.
+ These rules apply irrespective of the typeface used in the surrounding
+ text.
\end{quote}
For example,
@@ -251,7 +258,8 @@ Quote from NIST checklist:\footnote{
The digits of numerical values having more than four digits on either
side of the decimal marker are separated into groups of three using
a thin, fixed space counting from both the left and right of the decimal
- marker. Commas are not used to separate digits into groups of three.
+ marker.
+ Commas are not used to separate digits into groups of three.
\end{quote}
\begin{quote}
@@ -262,8 +270,9 @@ Quote from NIST checklist:\footnote{
\end{quote}
In \LaTeX\ coding, it is cumbersome to place thin spaces as are recommended
-in NIST guide. The \verb|\num{}| command provided by the ``siunitx''
-package would be of help for us to follow this rule.
+in NIST guide.
+The \verb|\num{}| command provided by the ``siunitx'' package would be
+of help for us to follow this rule.
It would also help us overcome different conventions.
We can select a specific digit-grouping style as
a default in preamble, or specify an option to each \verb|\num{}|
@@ -358,8 +367,9 @@ but those line numbers cannot be referenced within the \LaTeX\ sources.
Let's start by looking at how code snippets are coded in the current scheme.
There are three customized environments of \qco{Verbatim}.
\qco{VerbatimL} is for floating snippets within the \qco{listing}
-environment. \qco{VerbatimN} is for inline snippets with line count
-enabled. \qco{VerbatimU} is for inline snippets without line count.
+environment.
+\qco{VerbatimN} is for inline snippets with line count enabled.
+\qco{VerbatimU} is for inline snippets without line count.
They are defined in the preamble as shown below:
\begin{VerbatimU}
@@ -398,11 +408,12 @@ The \LaTeX\ source of a sample code snippet is shown in
and is typeset as shown in
\cref{lst:app:styleguide:Sample Code Snippet}.
-Labels to lines are specified in \qco{$lnlbl[]} command. The characters
-specified by \qco{commandchars} option to \co{VarbatimL} environment are
-used by the \co{fancyvrb} package to substitute \qco{\\lnlbl\{\}}
-for \qco{$lnlbl[]}. Those characters should be selected so that they
-don't appear elsewhere in the code snippet.
+Labels to lines are specified in \qco{$lnlbl[]} command.
+The characters specified by \qco{commandchars} option to \co{VarbatimL}
+environment are used by the \co{fancyvrb} package to substitute
+\qco{\\lnlbl\{\}} for \qco{$lnlbl[]}.
+Those characters should be selected so that they don't appear
+elsewhere in the code snippet.
Labels \qco{printf} and \qco{return} in
\cref{lst:app:styleguide:Sample Code Snippet}
@@ -453,9 +464,10 @@ The main part of \LaTeX\ source shown on
\cref{lst:app:styleguide:LaTeX Source of Sample Code Snippet (Current)}
can be extracted from a code sample of
\cref{lst:app:styleguide:Source of Code Sample} by a perl script
-\path{utilities/fcvextract.pl}. All the relevant rules of extraction
-are described as recipes in the top level \path{Makefile} and
-a script to generate dependencies (\path{utilities/gen_snippet_d.pl}).
+\path{utilities/fcvextract.pl}.
+All the relevant rules of extraction are described as recipes in the
+top level \path{Makefile} and a script to generate dependencies
+(\path{utilities/gen_snippet_d.pl}).
\end{fcvref}
\begin{listing*}
@@ -467,9 +479,10 @@ a script to generate dependencies (\path{utilities/gen_snippet_d.pl}).
\end{listing*}
As you can see, \cref{lst:app:styleguide:Source of Code Sample}
-has meta commands in comments of C (C++ style). Those meta commands
-are interpreted by \path{utilities/fcvextract.pl}, which distinguishes
-the type of comment style by the suffix of code sample's file name.
+has meta commands in comments of C (C++ style).
+Those meta commands are interpreted by \path{utilities/fcvextract.pl},
+which distinguishes the type of comment style by the suffix of code
+sample's file name.
Meta commands which can be used in code samples are listed below:
@@ -502,8 +515,9 @@ Otherwise, comment blocks in C source code will be omitted.
The \qco{gobbleblank=yes} option will remove empty or blank lines
in the resulting snippet.
The \qco{commandchars} option is given to the \co{VerbatimL} environment
-as is. At the moment, it is also mandatory
-and must come at the end of options listed above.
+as is.
+At the moment, it is also mandatory and must come at the end of options
+listed above.
Other types of options, if any, are also passed to the \co{VerbatimL}
environment.
@@ -534,18 +548,18 @@ They also forbid a couple of tokens to appear in comments.
For example, the first token in a litmus test must be one of
\qco{C}, \qco{PPC}, \qco{X86}, \qco{LISA}, etc., which indicates
-the flavor of the test. This means no comment is allowed
-at the beginning of a litmus test.
+the flavor of the test.
+This means no comment is allowed at the beginning of a litmus test.
Similarly, several tokens such as \qco{exists}, \qco{filter},
and~\qco{locations} indicate the end of litmus test's body.
Once one of them appears in a litmus test, comments should be of
-OCaml style (\qco{(* ... *)}). Those tokens keep the same meaning
-even when they appear in comments!
+OCaml style (\qco{(* ... *)}).
+Those tokens keep the same meaning even when they appear in comments!
The pair of characters \qco{\{} and \qco{\}} also have special
-meaning in the C flavour tests. They are used to separate portions
-in a litmus test.
+meaning in the C flavour tests.
+They are used to separate portions in a litmus test.
First pair of \qco{\{} and \qco{\}} encloses initialization part.
Comments in this part should also be in the ocaml form.
@@ -686,9 +700,9 @@ as follows:
\end{VerbatimU}
The \qco{verbatim} environment is used for listings with too many lines
-to fit in a column. It is also used to avoid overwhelming
-\LaTeX\ with a lot of floating objects. They are being converted to the
-scheme using the \co{VerbatimN} environment.
+to fit in a column.
+It is also used to avoid overwhelming \LaTeX\ with a lot of floating objects.
+They are being converted to the scheme using the \co{VerbatimN} environment.
\subsubsection{Identifier}
\label{sec:app:styleguide:Identifier}
@@ -697,12 +711,13 @@ We use ``\verb|\co{}|'' macro for inline identifiers.
(``co'' stands for ``code''.)
By putting them into \verb|\co{}|, underscore characters in
-their names are free of escaping in \LaTeX\ source. It is convenient
-to search them in source files. Also, \verb|\co{}|
-macro has a capability to permit line breaks at particular
-sequences of letters. Current definition permits a line break at
-an underscore (\tco{_}), two consecutive underscores (\tco{__}),
-a white space, or an operator \tco{->}.
+their names are free of escaping in \LaTeX\ source.
+It is convenient to search them in source files.
+Also, \verb|\co{}| macro has a capability to permit line breaks
+at particular sequences of letters.
+Current definition permits a line break at an underscore (\tco{_}),
+two consecutive underscores (\tco{__}), a white space, or an
+operator \tco{->}.
\subsubsection{Identifier inside Table and Heading}
\label{sec:app:styleguide:Identifier inside Table and Heading}
@@ -716,9 +731,9 @@ Furthermore, \verb|\co{}| can not be safely used in section headings nor
description headings.
As a workaround, we use ``\verb|\tco{}|'' command
-inside tables and headings. It has no capability of line break
-at particular sequences, but still frees us from escaping
-underscores.
+inside tables and headings.
+It has no capability of line break at particular sequences, but
+still frees us from escaping underscores.
When used in text, \verb|\tco{}| permits line breaks at
white spaces.
@@ -727,11 +742,11 @@ white spaces.
\label{sec:app:styleguide:Other Use Cases of Monospace Font}
For URLs, we use ``\verb|\url{}|'' command provided by the
-\qco{hyperref} package. It will generate hyper references to the
-URLs.
+\qco{hyperref} package.
+It will generate hyper references to the URLs.
-For path names, we use ``\verb|\path{}|'' command. It won't
-generate hyper references.
+For path names, we use ``\verb|\path{}|'' command.
+It won't generate hyper references.
Both \verb|\url{}| and \verb|\path{}| permit line breaks
at \qco{/}, \qco{-}, and \qco{.}.\footnote{
@@ -787,7 +802,7 @@ many characters to escape.\footnote{
Cross-references to \namecrefs{chp:Introduction},
\namecrefs{sec:intro:Parallel Programming Goals},
-\namecrefs{lst:app:styleguide:Source of Code Sample}, etc.\ have
+\namecrefs{lst:app:styleguide:Source of Code Sample}, etc.\@ have
been expressed by combinations of names and bare \verb|\ref{}|
commands in the following way:
@@ -843,9 +858,10 @@ info on its cleverness.
\label{sec:app:styleguide:Non Breakable Spaces}
In \LaTeX\ conventions, proper use of non-breakable white spaces
-is highly recommended. They can prevent widowing and orphaning
-of single digit numbers or short variable names, which would
-cause the text to be confusing at first glance.
+is highly recommended.
+They can prevent widowing and orphaning of single digit numbers
+or short variable names, which would cause the text to be confusing
+at first glance.
The thin space mentioned earlier to be placed in front of a unit
symbol is non breakable.
@@ -877,8 +893,9 @@ are the following (inexhaustive).
\label{sec:app:styleguide:Hyphenation in Compound Word}
In plain \LaTeX, compound words such as ``high-frequency''
-can be hyphenated only at the hyphen. This sometimes results
-in poor typesetting. For example:
+can be hyphenated only at the hyphen.
+This sometimes results in poor typesetting.
+For example:
\begin{center}\begin{minipage}{2.6in}\vspace{0.6\baselineskip}
High-frequency radio wave, high-frequency radio wave,
@@ -906,7 +923,7 @@ Example with \qco{\\-/}:
\label{sec:app:styleguide:Non Breakable Hyphen}
We want hyphenated compound terms such as ``x\=/coordinate'',
-``y\=/coordinate'', etc.\ not to be broken at the hyphen
+``y\=/coordinate'', etc.\@ not to be broken at the hyphen
following a single letter.
To make a hyphen unbreakable, we can use a short cut
@@ -942,9 +959,9 @@ of compound words as the same as \qco{\\-/} does.
\subsubsection{Em Dash}
\label{sec:app:styleguide:Em Dash}
-Em dashes are used to indicate parenthetic expression. In perfbook,
-em dashes are placed without spaces around it. In \LaTeX\ source,
-an em dash is represented by \qco{---}.
+Em dashes are used to indicate parenthetic expression.
+In perfbook, em dashes are placed without spaces around it.
+In \LaTeX\ source, an em dash is represented by \qco{---}.
Example (quote from \cref{sec:app:whymb:Cache Structure}):
\begin{quote}
@@ -972,8 +989,8 @@ Example with a simple dash:
\begin{fcvref}[ln:app:styleguide:samplecodesnippetlstlbl]
Lines~\lnref{b}\=/\lnref{e} in
\cref{lst:app:styleguide:LaTeX Source of Sample Code Snippet (Obsolete)}
- are the contents of the verbbox environment. The box is output
- by the \co{\\theverbbox} macro on \clnref{theverbbox}.
+ are the contents of the verbbox environment.
+ The box is output by the \co{\\theverbbox} macro on \clnref{theverbbox}.
\end{fcvref}
\end{quote}
@@ -983,8 +1000,8 @@ Example with an en dash:
\begin{fcvref}[ln:app:styleguide:samplecodesnippetlstlbl]
Lines~\lnref{b}\==\lnref{e} in
\cref{lst:app:styleguide:LaTeX Source of Sample Code Snippet (Obsolete)}
- are the contents of the verbbox environment. The box is output
- by the \co{\\theverbbox} macro on \clnref{theverbbox}.
+ are the contents of the verbbox environment.
+ The box is output by the \co{\\theverbbox} macro on \clnref{theverbbox}.
\end{fcvref}
\end{quote}
@@ -993,8 +1010,8 @@ Example with an en dash:
Numerical minus signs should be coded as math mode minus signs,
namely \qco{$-$}.\footnote{This rule assumes that math mode uses the
- same upright glyph as text mode. Our default font choice meets
- the assumption.
+ same upright glyph as text mode.
+ Our default font choice meets the assumption.
\IfSansSerif{
One of the experimental targets ``1csf'' \emph{does} use a differnt font
for math mode figures as of October 2017.}{}
@@ -1011,8 +1028,8 @@ For example,
\subsubsection{Ellipsis}
\label{sec:app:styleguide:Ellipsis}
-In monospace fonts, ellipses can be expressed by
-series of periods. For example:
+In monospace fonts, ellipses can be expressed by series of periods.
+For example:
\begin{quote}
\verb|Great ... So how do I fix it?|
@@ -1029,9 +1046,10 @@ Standard \LaTeX\ defines the \verb|\dots| macro for this purpose.
However, it has a kludge in the evenness of spaces.
The ``ellipsis'' package redefines the \verb|\dots| macro to fix
the issue.\footnote{To be exact, it is the \co{\\textellipsis} macro
- that is redefined. The behavior of \co{\\dots} macro in math
- mode is not affected. The ``amsmath'' package has another definition
- of \co{\\dots}. It is not used in perfbook at the moment.}
+ that is redefined.
+ The behavior of \co{\\dots} macro in math mode is not affected.
+ The ``amsmath'' package has another definition of \co{\\dots}.
+ It is not used in perfbook at the moment.}
By using \verb|\dots|, the above example is typeset as the following:
\begin{quote}
@@ -1149,7 +1167,8 @@ is drawn by using the features of ``booktabs'' and ``xcolor'' packages.
Note that ruled lines of booktabs can not be mixed with
vertical lines in a table.\footnote{
There is another package named ``arydshln'' which provides dashed lines
- to be used in tables. A couple of experimental examples are presented in
+ to be used in tables.
+ A couple of experimental examples are presented in
\cref{sec:app:styleguide:Table Layout Experiment}.
}
@@ -1190,10 +1209,11 @@ IBM~Q & $0.015$
\label{sec:app:styleguide:Position of Caption}
In \LaTeX\ conventions, captions of tables are usually placed
-above them. The reason is the flow of your eye movement
-when you look at them. Most tables have a row of heading at the
-top. You naturally look at the top of a table at first. Captions at
-the bottom of tables disturb this flow.
+above them.
+The reason is the flow of your eye movement when you look at them.
+Most tables have a row of heading at the top.
+You naturally look at the top of a table at first.
+Captions at the bottom of tables disturb this flow.
The same can be said of code snippets, which are read from
top to bottom.
@@ -1351,10 +1371,10 @@ and a \verb|\subref{}| macro, for example,
It can also be cited by a \verb|\ref{}| macro, for example,
``\cref{sublst:app:styleguide:Enforcing Order}''.
-Note the difference in the resulting format. For the citing by
-a \verb|\ref{}| to work, you need to place the \verb|\label{}|
-macro of the combined floating object ahead of the definition of
-subfloats.
+Note the difference in the resulting format.
+For the citing by a \verb|\ref{}| to work, you need to place
+the \verb|\label{}| macro of the combined floating object
+ahead of the definition of subfloats.
Otherwise, the resulting caption number would be off by one
from the actual number.
@@ -1364,8 +1384,9 @@ from the actual number.
This section presents some experimental tables
using booktabs, xcolors, and arydshln packages.
The corresponding tables in the text have been converted using one of
-the format shown here. The source of this section can be regarded
-as a reference to be consulted when new tables are added in the text.
+the format shown here.
+The source of this section can be regarded as a reference to be
+consulted when new tables are added in the text.
\begin{table}
\rowcolors{1}{}{lightgray}
@@ -1415,7 +1436,8 @@ In
the gap in the mid-rule corresponds to the distinction
which had been represented by double vertical rules before the conversion.
The legends in the frame box appended here explain the abbreviations used
-in the matrix. Two types of memory barrier are denoted by subscripts here.
+in the matrix.
+Two types of memory barrier are denoted by subscripts here.
The legends and subscripts are not present in
\cref{tab:together:Synchronizing Reference Counting}
since they are redundant there.
@@ -1508,15 +1530,16 @@ is a tweaked version of
\cref{tab:defer:RCU Publish-Subscribe and Version Maintenance APIs}.
Here, the ``Category'' column in the original is removed
and the categories are indicated in rows of bold-face font
-just below the mid-rules. This change makes it easier for
-\verb|\rowcolors{}| command of ``xcolor'' package to work
-properly.
+just below the mid-rules.
+This change makes it easier for \verb|\rowcolors{}| command of
+``xcolor'' package to work properly.
\Cref{tab:app:styleguide:RCU Publish-Subscribe and Version Maintenance APIs (colortbl)}
is another version which keeps original columns and colors rows only where
-a category has multiple rows. This is done by combining \verb|\rowcolors{}|
-of ``xcolor'' and \verb|\cellcolor{}| commands of the ``colortbl''
-package (\verb|\cellcolor{}| overrides \verb|\rowcolors{}|).
+a category has multiple rows.
+This is done by combining \verb|\rowcolors{}| of ``xcolor'' and
+\verb|\cellcolor{}| commands of the ``colortbl'' package
+(\verb|\cellcolor{}| overrides \verb|\rowcolors{}|).
In
\cref{tab:defer:RCU Publish-Subscribe and Version Maintenance APIs},
--
2.17.1
^ permalink raw reply related [flat|nested] 15+ messages in thread* [PATCH -perfbook v2 8/9] treewide: Fix space in front of \cite{}
2021-04-27 15:18 [PATCH -perfbook v2 0/9] Add script to check period spacing Akira Yokosawa
` (6 preceding siblings ...)
2021-04-27 15:30 ` [PATCH -perfbook v2 7/9] styleguide: Make end-of-sentence periods be at the " Akira Yokosawa
@ 2021-04-27 15:31 ` Akira Yokosawa
2021-04-27 15:33 ` [PATCH -perfbook v2 9/9] treewide: Substitute ';' for ',' in label strings Akira Yokosawa
2021-04-27 15:51 ` [PATCH -perfbook v2 0/9] Add script to check period spacing Paul E. McKenney
9 siblings, 0 replies; 15+ messages in thread
From: Akira Yokosawa @ 2021-04-27 15:31 UTC (permalink / raw)
To: Paul E. McKenney; +Cc: perfbook, Akira Yokosawa
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
debugging/debugging.tex | 4 ++--
formal/ppcmem.tex | 4 ++--
intro/intro.tex | 2 +-
3 files changed, 5 insertions(+), 5 deletions(-)
diff --git a/debugging/debugging.tex b/debugging/debugging.tex
index 4c77453d..7d739a62 100644
--- a/debugging/debugging.tex
+++ b/debugging/debugging.tex
@@ -760,8 +760,8 @@ viewpoint of developers thinking in terms of C as assembly language
with additional syntax.
KCSAN therefore provides a \co{data_race()} construct to forgive
known-benign \IXpl{data race}, and also the \co{ASSERT_EXCLUSIVE_ACCESS()}
-and \co{ASSERT_EXCLUSIVE_WRITER()} assertions to explicitly check
-for data races\cite{MarcoElver2020FearDataRaceDetector1,MarcoElver2020FearDataRaceDetector2}.
+and \co{ASSERT_EXCLUSIVE_WRITER()} assertions to explicitly check for data
+races~\cite{MarcoElver2020FearDataRaceDetector1,MarcoElver2020FearDataRaceDetector2}.
So what can be done in cases where checking is necessary, but where the
overhead of runtime checking cannot be tolerated?
diff --git a/formal/ppcmem.tex b/formal/ppcmem.tex
index 019d0161..349ec072 100644
--- a/formal/ppcmem.tex
+++ b/formal/ppcmem.tex
@@ -356,8 +356,8 @@ cannot happen.
on both sides.
The ordering provided by \co{lwsync} is insufficient for this
purpose, and so \co{sync} should be used instead.
- This change has since been made~%
- \cite{BoqunFeng2015:powerpc:value-returning-atomics}
+ This change has since been
+ made~\cite{BoqunFeng2015:powerpc:value-returning-atomics}
in response to an email thread discussing a couple of other litmus
tests~\cite{Paulmck2015:powerpc:value-returning-atomics}.
Finding any other bugs that the Linux kernel might have is left
diff --git a/intro/intro.tex b/intro/intro.tex
index 812b34fd..852ea82d 100644
--- a/intro/intro.tex
+++ b/intro/intro.tex
@@ -41,7 +41,7 @@ social-networking tools.
As recently as 1968, such content creation was a far-out research
project~\cite{DouglasEngelbart1968}, described at
the time as
-``like a UFO landing on the White House lawn''\cite{ScottGriffen2000}.
+``like a UFO landing on the White House lawn''~\cite{ScottGriffen2000}.
% http://www.ibiblio.org/pioneers/engelbart.html
% http://www.histech.rwth-aachen.de/www/quellen/engelbart/ahi62index.html
--
2.17.1
^ permalink raw reply related [flat|nested] 15+ messages in thread* [PATCH -perfbook v2 9/9] treewide: Substitute ';' for ',' in label strings
2021-04-27 15:18 [PATCH -perfbook v2 0/9] Add script to check period spacing Akira Yokosawa
` (7 preceding siblings ...)
2021-04-27 15:31 ` [PATCH -perfbook v2 8/9] treewide: Fix space in front of \cite{} Akira Yokosawa
@ 2021-04-27 15:33 ` Akira Yokosawa
2021-04-27 15:51 ` [PATCH -perfbook v2 0/9] Add script to check period spacing Paul E. McKenney
9 siblings, 0 replies; 15+ messages in thread
From: Akira Yokosawa @ 2021-04-27 15:33 UTC (permalink / raw)
To: Paul E. McKenney; +Cc: perfbook, Akira Yokosawa
periodcheck.pl relies on this change for "vs." within label
strings to be ignored.
This change is also required for treewide conversion to
\cref{}/\Cref{} and their variants.
"," is a delimiter of label strings in those cleveref macros.
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
SMPdesign/beyond.tex | 12 +++++------
SMPdesign/partexercises.tex | 12 +++++------
cpu/hwfreelunch.tex | 2 +-
datastruct/datastruct.tex | 40 +++++++++++++++++------------------
defer/rcuapi.tex | 4 ++--
defer/refcnt.tex | 4 ++--
intro/intro.tex | 4 ++--
toolsoftrade/toolsoftrade.tex | 6 +++---
8 files changed, 42 insertions(+), 42 deletions(-)
diff --git a/SMPdesign/beyond.tex b/SMPdesign/beyond.tex
index bd0fe6f1..20b6a9e2 100644
--- a/SMPdesign/beyond.tex
+++ b/SMPdesign/beyond.tex
@@ -370,11 +370,11 @@ array, and line~\lnref{ret:success} returns success.
\centering
\resizebox{2.2in}{!}{\includegraphics{SMPdesign/500-ms_seq_fg_part-cdf}}
\caption{CDF of Solution Times For SEQ, PWQ, and PART}
-\label{fig:SMPdesign:CDF of Solution Times For SEQ, PWQ, and PART}
+\label{fig:SMPdesign:CDF of Solution Times For SEQ; PWQ; and PART}
\end{figure}
Performance testing revealed a surprising anomaly, shown in
-Figure~\ref{fig:SMPdesign:CDF of Solution Times For SEQ, PWQ, and PART}.
+Figure~\ref{fig:SMPdesign:CDF of Solution Times For SEQ; PWQ; and PART}.
The median solution time for PART (17 milliseconds)
is more than four times faster than that of SEQ (79 milliseconds),
despite running on only two threads.
@@ -393,7 +393,7 @@ The next section analyzes this anomaly.
The first reaction to a performance anomaly is to check for bugs.
Although the algorithms were in fact finding valid solutions, the
plot of CDFs in
-Figure~\ref{fig:SMPdesign:CDF of Solution Times For SEQ, PWQ, and PART}
+Figure~\ref{fig:SMPdesign:CDF of Solution Times For SEQ; PWQ; and PART}
assumes independent data points.
This is not the case: The performance tests randomly generate a maze,
and then run all solvers on that maze.
@@ -577,10 +577,10 @@ were generated using -O3.
\centering
\resizebox{2.2in}{!}{\includegraphics{SMPdesign/1000-ms_2seqO3VfgO3_partO3-mean}}
\caption{Mean Speedup vs.\@ Number of Threads, 1000x1000 Maze}
-\label{fig:SMPdesign:Mean Speedup vs. Number of Threads, 1000x1000 Maze}
+\label{fig:SMPdesign:Mean Speedup vs. Number of Threads; 1000x1000 Maze}
\end{figure}
-Figure~\ref{fig:SMPdesign:Mean Speedup vs. Number of Threads, 1000x1000 Maze}
+Figure~\ref{fig:SMPdesign:Mean Speedup vs. Number of Threads; 1000x1000 Maze}
shows the performance of PWQ and PART relative to COPART\@.
For PART runs with more than two threads, the additional threads were
started evenly spaced along the diagonal connecting the starting and
@@ -650,7 +650,7 @@ rather than as a grossly suboptimal after-the-fact micro-optimization
to be retrofitted into existing programs.
\section{Partitioning, Parallelism, and Optimization}
-\label{sec:SMPdesign:Partitioning, Parallelism, and Optimization}
+\label{sec:SMPdesign:Partitioning; Parallelism; and Optimization}
%
\epigraph{Knowledge is of no value unless you put it into practice.}
{\emph{Anton Chekhov}}
diff --git a/SMPdesign/partexercises.tex b/SMPdesign/partexercises.tex
index 8a56663e..a84cc74f 100644
--- a/SMPdesign/partexercises.tex
+++ b/SMPdesign/partexercises.tex
@@ -64,7 +64,7 @@ shows, starvation of even a few of the philosophers is to be avoided.
\centering
\includegraphics[scale=.7]{SMPdesign/DiningPhilosopher5TB}
\caption{Dining Philosophers Problem, Textbook Solution}
-\ContributedBy{Figure}{fig:SMPdesign:Dining Philosophers Problem, Textbook Solution}{Kornilios Kourtis}
+\ContributedBy{Figure}{fig:SMPdesign:Dining Philosophers Problem; Textbook Solution}{Kornilios Kourtis}
\end{figure}
\pplsur{Edsger W.}{Dijkstra}'s solution used a global semaphore,
@@ -77,7 +77,7 @@ in the late 1980s or early 1990s.\footnote{
is to publish something, wait 50 years, and then see
how well \emph{your} ideas stood the test of time.}
More recent solutions number the forks as shown in
-Figure~\ref{fig:SMPdesign:Dining Philosophers Problem, Textbook Solution}.
+Figure~\ref{fig:SMPdesign:Dining Philosophers Problem; Textbook Solution}.
Each philosopher picks up the lowest-numbered fork next to his or her
plate, then picks up the other fork.
The philosopher sitting in the uppermost position in the diagram thus
@@ -114,11 +114,11 @@ It should be possible to do better than this!
\centering
\includegraphics[scale=.7]{SMPdesign/DiningPhilosopher4part-b}
\caption{Dining Philosophers Problem, Partitioned}
-\ContributedBy{Figure}{fig:SMPdesign:Dining Philosophers Problem, Partitioned}{Kornilios Kourtis}
+\ContributedBy{Figure}{fig:SMPdesign:Dining Philosophers Problem; Partitioned}{Kornilios Kourtis}
\end{figure}
One approach is shown in
-Figure~\ref{fig:SMPdesign:Dining Philosophers Problem, Partitioned},
+Figure~\ref{fig:SMPdesign:Dining Philosophers Problem; Partitioned},
which includes four philosophers rather than five to better illustrate the
partition technique.
Here the upper and rightmost philosophers share a pair of forks,
@@ -134,7 +134,7 @@ the acquisition and release algorithms.
Philosophers Problem?
}\QuickQuizAnswer{
One such improved solution is shown in
- Figure~\ref{fig:SMPdesign:Dining Philosophers Problem, Fully Partitioned},
+ Figure~\ref{fig:SMPdesign:Dining Philosophers Problem; Fully Partitioned},
where the philosophers are simply provided with an additional
five forks.
All five philosophers may now eat simultaneously, and there
@@ -145,7 +145,7 @@ the acquisition and release algorithms.
\centering
\includegraphics[scale=.7]{SMPdesign/DiningPhilosopher5PEM}
\caption{Dining Philosophers Problem, Fully Partitioned}
-\QContributedBy{Figure}{fig:SMPdesign:Dining Philosophers Problem, Fully Partitioned}{Kornilios Kourtis}
+\QContributedBy{Figure}{fig:SMPdesign:Dining Philosophers Problem; Fully Partitioned}{Kornilios Kourtis}
\end{figure}
This solution might seem like cheating to some, but such
diff --git a/cpu/hwfreelunch.tex b/cpu/hwfreelunch.tex
index a2e85950..c4a9b495 100644
--- a/cpu/hwfreelunch.tex
+++ b/cpu/hwfreelunch.tex
@@ -196,7 +196,7 @@ atoms on each of the billions of devices on a chip will have most
excellent bragging rights, if nothing else!
\subsection{Light, Not Electrons}
-\label{sec:cpu:Light, Not Electrons}
+\label{sec:cpu:Light; Not Electrons}
Although the speed of light would be a hard limit, the fact is that
semiconductor devices are limited by the speed of electricity rather
diff --git a/datastruct/datastruct.tex b/datastruct/datastruct.tex
index 6e18fda9..038f3923 100644
--- a/datastruct/datastruct.tex
+++ b/datastruct/datastruct.tex
@@ -345,11 +345,11 @@ We can test this by increasing the number of hash buckets.
\centering
\resizebox{2.5in}{!}{\includegraphics{CodeSamples/datastruct/hash/data/hps.perf.2020.11.26a/zoocpubktsizelin}}
\caption{Read-Only Hash-Table Performance For Schr\"odinger's Zoo, Varying Buckets}
-\label{fig:datastruct:Read-Only Hash-Table Performance For Schroedinger's Zoo, Varying Buckets}
+\label{fig:datastruct:Read-Only Hash-Table Performance For Schroedinger's Zoo; Varying Buckets}
\end{figure}
However, as can be seen in
-Figure~\ref{fig:datastruct:Read-Only Hash-Table Performance For Schroedinger's Zoo, Varying Buckets},
+Figure~\ref{fig:datastruct:Read-Only Hash-Table Performance For Schroedinger's Zoo; Varying Buckets},
changing the number of buckets has almost no effect:
Scalability is still abysmal.
In particular, we still see a sharp dropoff at 29~CPUs and beyond.
@@ -584,10 +584,10 @@ RCU does slightly better than hazard pointers.
\centering
\resizebox{2.5in}{!}{\includegraphics{CodeSamples/datastruct/hash/data/hps.perf.2020.11.26a/zoocpulin}}
\caption{Read-Only RCU-Protected Hash-Table Performance For Schr\"odinger's Zoo, Linear Scale}
-\label{fig:datastruct:Read-Only RCU-Protected Hash-Table Performance For Schroedinger's Zoo, Linear Scale}
+\label{fig:datastruct:Read-Only RCU-Protected Hash-Table Performance For Schroedinger's Zoo; Linear Scale}
\end{figure}
-Figure~\ref{fig:datastruct:Read-Only RCU-Protected Hash-Table Performance For Schroedinger's Zoo, Linear Scale}
+Figure~\ref{fig:datastruct:Read-Only RCU-Protected Hash-Table Performance For Schroedinger's Zoo; Linear Scale}
shows the same data on a linear scale.
This drops the global-locking trace into the x-axis, but allows the
non-ideal performance of RCU and hazard pointers to be more readily
@@ -615,13 +615,13 @@ advantage depends on the workload.
\centering
\resizebox{2.5in}{!}{\includegraphics{CodeSamples/datastruct/hash/data/hps.perf.2020.11.26a/zoocpulinqsbr}}
\caption{Read-Only RCU-Protected Hash-Table Performance For Schr\"odinger's Zoo including QSBR, Linear Scale}
-\label{fig:datastruct:Read-Only RCU-Protected Hash-Table Performance For Schroedinger's Zoo including QSBR, Linear Scale}
+\label{fig:datastruct:Read-Only RCU-Protected Hash-Table Performance For Schroedinger's Zoo including QSBR; Linear Scale}
\end{figure}
But why is RCU's performance a factor of five less than ideal?
One possibility is that the per-thread counters manipulated by
\co{rcu_read_lock()} and \co{rcu_read_unlock()} are slowing things down.
-Figure~\ref{fig:datastruct:Read-Only RCU-Protected Hash-Table Performance For Schroedinger's Zoo including QSBR, Linear Scale}
+Figure~\ref{fig:datastruct:Read-Only RCU-Protected Hash-Table Performance For Schroedinger's Zoo including QSBR; Linear Scale}
therefore adds the results for the QSBR variant of RCU, whose read-side
primitives do nothing.
And although QSBR does perform slightly better than does RCU, it is still
@@ -631,10 +631,10 @@ about a factor of five short of ideal.
\centering
\resizebox{2.5in}{!}{\includegraphics{CodeSamples/datastruct/hash/data/hps.perf.2020.11.26a/zoocpulinqsbrunsync}}
\caption{Read-Only RCU-Protected Hash-Table Performance For Schr\"odinger's Zoo including QSBR and Unsynchronized, Linear Scale}
-\label{fig:datastruct:Read-Only RCU-Protected Hash-Table Performance For Schroedinger's Zoo including QSBR and Unsynchronized, Linear Scale}
+\label{fig:datastruct:Read-Only RCU-Protected Hash-Table Performance For Schroedinger's Zoo including QSBR and Unsynchronized; Linear Scale}
\end{figure}
-Figure~\ref{fig:datastruct:Read-Only RCU-Protected Hash-Table Performance For Schroedinger's Zoo including QSBR and Unsynchronized, Linear Scale}
+Figure~\ref{fig:datastruct:Read-Only RCU-Protected Hash-Table Performance For Schroedinger's Zoo including QSBR and Unsynchronized; Linear Scale}
adds completely unsynchronized results, which works because this
is a read-only benchmark with nothing to synchronize.
Even with no synchronization whatsoever, performance still falls far
@@ -647,7 +647,7 @@ on page~\pageref{tab:cpu:Cache Geometry for 8-Socket System With Intel Xeon Plat
Each hash bucket (\co{struct ht_bucket}) occupies 56~bytes and each
element (\co{struct zoo_he}) occupies 72~bytes for the RCU and QSBR runs.
The benchmark generating
-Figure~\ref{fig:datastruct:Read-Only RCU-Protected Hash-Table Performance For Schroedinger's Zoo including QSBR and Unsynchronized, Linear Scale}
+Figure~\ref{fig:datastruct:Read-Only RCU-Protected Hash-Table Performance For Schroedinger's Zoo including QSBR and Unsynchronized; Linear Scale}
used 262,144 buckets and up to 262,144 elements, for a total of
33,554,448~bytes, which not only overflows the 1,048,576-byte L2 caches
by more than a factor of thirty, but is also uncomfortably close to the
@@ -681,8 +681,8 @@ to about half again faster than that of either QSBR or RCU\@.
\QuickQuiz{
How can we be so sure that the hash-table size is at fault here,
especially given that
- Figure~\ref{fig:datastruct:Read-Only Hash-Table Performance For Schroedinger's Zoo, Varying Buckets}
- on page~\pageref{fig:datastruct:Read-Only Hash-Table Performance For Schroedinger's Zoo, Varying Buckets}
+ Figure~\ref{fig:datastruct:Read-Only Hash-Table Performance For Schroedinger's Zoo; Varying Buckets}
+ on page~\pageref{fig:datastruct:Read-Only Hash-Table Performance For Schroedinger's Zoo; Varying Buckets}
shows that varying hash-table size has almost
no effect?
Might the problem instead be something like false sharing?
@@ -698,12 +698,12 @@ to about half again faster than that of either QSBR or RCU\@.
\centering
\resizebox{3in}{!}{\includegraphics{CodeSamples/datastruct/hash/data/hps.perf-hashsize.2020.12.29a/zoohashsize}}
\caption{Read-Only RCU-Protected Hash-Table Performance For Schr\"odinger's Zoo at 448 CPUs, Varying Table Size}
-\label{fig:datastruct:Read-Only RCU-Protected Hash-Table Performance For Schr\"odinger's Zoo at 448 CPUs, Varying Table Size}
+\label{fig:datastruct:Read-Only RCU-Protected Hash-Table Performance For Schr\"odinger's Zoo at 448 CPUs; Varying Table Size}
\end{figure}
Still unconvinced?
Then look at the log-log plot in
- Figure~\ref{fig:datastruct:Read-Only RCU-Protected Hash-Table Performance For Schr\"odinger's Zoo at 448 CPUs, Varying Table Size},
+ Figure~\ref{fig:datastruct:Read-Only RCU-Protected Hash-Table Performance For Schr\"odinger's Zoo at 448 CPUs; Varying Table Size},
which shows performance for 448 CPUs as a function of the
hash-table size, that is, number of buckets and maximum number
of elements.
@@ -734,8 +734,8 @@ to about half again faster than that of either QSBR or RCU\@.
a factor of 25.
The reason that
- Figure~\ref{fig:datastruct:Read-Only Hash-Table Performance For Schroedinger's Zoo, Varying Buckets}
- on page~\pageref{fig:datastruct:Read-Only Hash-Table Performance For Schroedinger's Zoo, Varying Buckets}
+ Figure~\ref{fig:datastruct:Read-Only Hash-Table Performance For Schroedinger's Zoo; Varying Buckets}
+ on page~\pageref{fig:datastruct:Read-Only Hash-Table Performance For Schroedinger's Zoo; Varying Buckets}
shows little effect is that its data was gathered from
bucket-locked hash tables, where locking overhead and contention
drowned out cache-capacity effects.
@@ -1514,11 +1514,11 @@ the old hash table, and finally line~\lnref{ret_success} returns success.
\centering
\resizebox{2.7in}{!}{\includegraphics{datastruct/perftestresize}}
\caption{Overhead of Resizing Hash Tables Between 262,144 and 524,288 Buckets vs.\@ Total Number of Elements}
-\label{fig:datastruct:Overhead of Resizing Hash Tables Between 262,144 and 524,288 Buckets vs. Total Number of Elements}
+\label{fig:datastruct:Overhead of Resizing Hash Tables Between 262;144 and 524;288 Buckets vs. Total Number of Elements}
\end{figure}
% Data from CodeSamples/datastruct/hash/data/hps.resize.2020.09.05a
-Figure~\ref{fig:datastruct:Overhead of Resizing Hash Tables Between 262,144 and 524,288 Buckets vs. Total Number of Elements}
+Figure~\ref{fig:datastruct:Overhead of Resizing Hash Tables Between 262;144 and 524;288 Buckets vs. Total Number of Elements}
compares resizing hash tables to their fixed-sized counterparts
for 262,144 and 2,097,152 elements in the hash table.
The figure shows three traces for each element count, one
@@ -1558,7 +1558,7 @@ bottleneck.
\QuickQuiz{
How much of the difference in performance between the large and
small hash tables shown in
- Figure~\ref{fig:datastruct:Overhead of Resizing Hash Tables Between 262,144 and 524,288 Buckets vs. Total Number of Elements}
+ Figure~\ref{fig:datastruct:Overhead of Resizing Hash Tables Between 262;144 and 524;288 Buckets vs. Total Number of Elements}
was due to long hash chains and how much was due to
memory-system bottlenecks?
}\QuickQuizAnswer{
@@ -1579,8 +1579,8 @@ bottleneck.
the middle of
\cref{fig:datastruct:Effect of Memory-System Bottlenecks on Hash Tables}.
The other six traces are identical to their counterparts in
- Figure~\ref{fig:datastruct:Overhead of Resizing Hash Tables Between 262,144 and 524,288 Buckets vs. Total Number of Elements}
- on page~\pageref{fig:datastruct:Overhead of Resizing Hash Tables Between 262,144 and 524,288 Buckets vs. Total Number of Elements}.
+ Figure~\ref{fig:datastruct:Overhead of Resizing Hash Tables Between 262;144 and 524;288 Buckets vs. Total Number of Elements}
+ on page~\pageref{fig:datastruct:Overhead of Resizing Hash Tables Between 262;144 and 524;288 Buckets vs. Total Number of Elements}.
The gap between this new trace and the lower set of three
traces is a rough measure of how much of the difference in
performance was due to hash-chain length, and the gap between
diff --git a/defer/rcuapi.tex b/defer/rcuapi.tex
index 315318c0..a7de666c 100644
--- a/defer/rcuapi.tex
+++ b/defer/rcuapi.tex
@@ -20,7 +20,7 @@ presents RCU's diagnostic APIs, and
Section~\ref{sec:defer:Where Can RCU's APIs Be Used?}
describes in which contexts RCU's various APIs may be used.
Finally,
-Section~\ref{sec:defer:So, What is RCU Really?}
+Section~\ref{sec:defer:So; What is RCU Really?}
presents concluding remarks.
Readers who are not excited about kernel internals may wish to skip
@@ -1097,7 +1097,7 @@ for example, \co{srcu_read_lock()} may be used in any context
in which \co{rcu_read_lock()} may be used.
\subsubsection{So, What \emph{is} RCU Really?}
-\label{sec:defer:So, What is RCU Really?}
+\label{sec:defer:So; What is RCU Really?}
At its core, RCU is nothing more nor less than an API that supports
publication and subscription for insertions, waiting for all RCU readers
diff --git a/defer/refcnt.tex b/defer/refcnt.tex
index 1573a927..4f815266 100644
--- a/defer/refcnt.tex
+++ b/defer/refcnt.tex
@@ -182,10 +182,10 @@ the atoms used in modern digital electronics.
\centering
\resizebox{2.5in}{!}{\includegraphics{CodeSamples/defer/perf-refcnt-logscale}}
\caption{Pre-BSD Routing Table Protected by Reference Counting, Log Scale}
-\label{fig:defer:Pre-BSD Routing Table Protected by Reference Counting, Log Scale}
+\label{fig:defer:Pre-BSD Routing Table Protected by Reference Counting; Log Scale}
\end{figure}
- Figure~\ref{fig:defer:Pre-BSD Routing Table Protected by Reference Counting, Log Scale}
+ Figure~\ref{fig:defer:Pre-BSD Routing Table Protected by Reference Counting; Log Scale}
shows the same data, but on a log-log plot.
As you can see, the refcnt line drops below 5,000 at two CPUs.
This means that the refcnt performance at two CPUs is more than
diff --git a/intro/intro.tex b/intro/intro.tex
index 852ea82d..77e89f3c 100644
--- a/intro/intro.tex
+++ b/intro/intro.tex
@@ -592,7 +592,7 @@ programming environments:
\centering
\resizebox{2.5in}{!}{\includegraphics{intro/PPGrelation}}
\caption{Software Layers and Performance, Productivity, and Generality}
-\label{fig:intro:Software Layers and Performance, Productivity, and Generality}
+\label{fig:intro:Software Layers and Performance; Productivity; and Generality}
\end{figure}
The nirvana of parallel programming environments, one that offers
@@ -601,7 +601,7 @@ not yet exist.
Until such a nirvana appears, it will be necessary to make engineering
tradeoffs among performance, productivity, and generality.
One such tradeoff is shown in
-Figure~\ref{fig:intro:Software Layers and Performance, Productivity, and Generality},
+Figure~\ref{fig:intro:Software Layers and Performance; Productivity; and Generality},
which shows how productivity becomes increasingly important at the upper layers
of the system stack,
while performance and generality become increasingly important at the
diff --git a/toolsoftrade/toolsoftrade.tex b/toolsoftrade/toolsoftrade.tex
index b358c22d..f9a8ee90 100644
--- a/toolsoftrade/toolsoftrade.tex
+++ b/toolsoftrade/toolsoftrade.tex
@@ -1231,7 +1231,7 @@ code or whether the kernel's boot-time code is in fact the required
initialization code.
\subsection{Thread Creation, Destruction, and Control}
-\label{sec:toolsoftrade:Thread Creation, Destruction, and Control}
+\label{sec:toolsoftrade:Thread Creation; Destruction; and Control}
The Linux kernel uses
\apik{struct task_struct} pointers to track kthreads,
@@ -2135,7 +2135,7 @@ if (ptr != NULL && ptr < high_address)
\end{VerbatimL}
\end{fcvlabel}
\caption{Avoiding Danger, 2018 Style}
-\label{lst:toolsoftrade:Avoiding Danger, 2018 Style}
+\label{lst:toolsoftrade:Avoiding Danger; 2018 Style}
\end{listing}
Using \apik{READ_ONCE()} on
@@ -2143,7 +2143,7 @@ line~\ref{ln:toolsoftrade:Living Dangerously Early 1990s Style:temp} of
Listing~\ref{lst:toolsoftrade:Living Dangerously Early 1990s Style}
avoids invented loads,
resulting in the code shown in
-Listing~\ref{lst:toolsoftrade:Avoiding Danger, 2018 Style}.
+Listing~\ref{lst:toolsoftrade:Avoiding Danger; 2018 Style}.
\begin{listing}
\begin{fcvlabel}[ln:toolsoftrade:Preventing Load Fusing]
--
2.17.1
^ permalink raw reply related [flat|nested] 15+ messages in thread* Re: [PATCH -perfbook v2 0/9] Add script to check period spacing
2021-04-27 15:18 [PATCH -perfbook v2 0/9] Add script to check period spacing Akira Yokosawa
` (8 preceding siblings ...)
2021-04-27 15:33 ` [PATCH -perfbook v2 9/9] treewide: Substitute ';' for ',' in label strings Akira Yokosawa
@ 2021-04-27 15:51 ` Paul E. McKenney
2021-04-27 22:32 ` Akira Yokosawa
9 siblings, 1 reply; 15+ messages in thread
From: Paul E. McKenney @ 2021-04-27 15:51 UTC (permalink / raw)
To: Akira Yokosawa; +Cc: perfbook
On Wed, Apr 28, 2021 at 12:18:56AM +0900, Akira Yokosawa wrote:
> Hi Paul,
>
> This patch set adds a set of scripts to check proper annotation
> of periods to distinguish single and double spacing.
>
> Patch 1/9 adds a couple of annotations in-development version of
> the script had caught.
> Patches 2/9--5/9 add and improve the set of scripts.
> They are kept separate patches to show the history.
> Patches 6/9--9/9 are fixes in LaTeX sources to satisfy the script.
> There are quite a few sentences which end in the middle of
> input lines.
>
> After Patch 9/9 is applied, "make periodcheck" will be clean.
>
> I'm not saying the perl script is complete.
> There can still be false negatives I'm not aware of.
> False positives can happen when you add new contents.
Queued and pushed, thank you!
Would it make sense at some point to have "make periodcheck" happen
automatically during a normal build to catch addition of issues with
new content?
Thanx, Paul
> Thanks, Akira
> --
> Akira Yokosawa (9):
> Annotate mid-sentence and end-of-sentence periods
> periodcheck: Add script to check missing annotation of period
> periodcheck: Add check of nbsp in front of \cite{}
> periodcheck: Improve label string matching
> periodcheck: Replace escaped percent symbol first
> treewide: Make end-of-sentence periods be at end of lines
> styleguide: Make end-of-sentence periods be at the end of lines
> treewide: Fix space in front of \cite{}
> treewide: Substitute ';' for ',' in label strings
>
> Makefile | 5 +-
> SMPdesign/SMPdesign.tex | 36 ++--
> SMPdesign/beyond.tex | 15 +-
> SMPdesign/criteria.tex | 4 +-
> SMPdesign/partexercises.tex | 12 +-
> ack.tex | 2 +-
> advsync/rt.tex | 7 +-
> appendix/styleguide/styleguide.tex | 237 +++++++++++++++------------
> appendix/whymb/whymemorybarriers.tex | 71 ++++----
> count/count.tex | 11 +-
> cpu/hwfreelunch.tex | 2 +-
> datastruct/datastruct.tex | 55 ++++---
> debugging/debugging.tex | 16 +-
> defer/defer.tex | 4 +-
> defer/hazptr.tex | 7 +-
> defer/rcuapi.tex | 4 +-
> defer/rcufundamental.tex | 5 +-
> defer/refcnt.tex | 4 +-
> easy/easy.tex | 3 +-
> formal/dyntickrcu.tex | 15 +-
> formal/ppcmem.tex | 184 +++++++++++----------
> formal/spinhint.tex | 148 +++++++++--------
> glossary.tex | 9 +-
> howto/howto.tex | 2 +-
> intro/intro.tex | 33 ++--
> legal.tex | 9 +-
> locking/locking.tex | 5 +-
> memorder/memorder.tex | 12 +-
> owned/owned.tex | 5 +-
> together/refcnt.tex | 4 +-
> toolsoftrade/toolsoftrade.tex | 9 +-
> utilities/periodcheck.pl | 87 ++++++++++
> utilities/periodcheck.sh | 23 +++
> 33 files changed, 627 insertions(+), 418 deletions(-)
> create mode 100755 utilities/periodcheck.pl
> create mode 100755 utilities/periodcheck.sh
>
> --
> 2.17.1
>
>
^ permalink raw reply [flat|nested] 15+ messages in thread* Re: [PATCH -perfbook v2 0/9] Add script to check period spacing
2021-04-27 15:51 ` [PATCH -perfbook v2 0/9] Add script to check period spacing Paul E. McKenney
@ 2021-04-27 22:32 ` Akira Yokosawa
2021-04-27 22:52 ` Paul E. McKenney
0 siblings, 1 reply; 15+ messages in thread
From: Akira Yokosawa @ 2021-04-27 22:32 UTC (permalink / raw)
To: Paul E. McKenney; +Cc: perfbook, Akira Yokosawa
On Tue, 27 Apr 2021 08:51:26 -0700, Paul E. McKenney wrote:
> On Wed, Apr 28, 2021 at 12:18:56AM +0900, Akira Yokosawa wrote:
>> Hi Paul,
>>
>> This patch set adds a set of scripts to check proper annotation
>> of periods to distinguish single and double spacing.
>>
>> Patch 1/9 adds a couple of annotations in-development version of
>> the script had caught.
>> Patches 2/9--5/9 add and improve the set of scripts.
>> They are kept separate patches to show the history.
>> Patches 6/9--9/9 are fixes in LaTeX sources to satisfy the script.
>> There are quite a few sentences which end in the middle of
>> input lines.
>>
>> After Patch 9/9 is applied, "make periodcheck" will be clean.
>>
>> I'm not saying the perl script is complete.
>> There can still be false negatives I'm not aware of.
>> False positives can happen when you add new contents.
>
> Queued and pushed, thank you!
>
> Would it make sense at some point to have "make periodcheck" happen
> automatically during a normal build to catch addition of issues with
> new content?
>
> Thanx, Paul
Like this?
Note that positive periodcheck doesn't cause a make error.
It can be promoted to a real error later when we feel confident of
the script.
"make 2c" (or any explicit target) doesn't run the script.
Thanks, Akira
--------8<--------------------------
From: Akira Yokosawa <akiyks@gmail.com>
Date: Wed, 28 Apr 2021 07:26:05 +0900
Subject: [PATCH] Auto run periodcheck on 'make'
Run periodcheck on "make" and "make all".
Now they are the same as "make periodcheck".
"make periodcheck" builds your default target before the check.
Suggested-by: Paul E. McKenney <paulmck@kernel.org>
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
Makefile | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/Makefile b/Makefile
index ea264dc5..792fa285 100644
--- a/Makefile
+++ b/Makefile
@@ -194,7 +194,7 @@ BASE_DEPENDS := perfbook.tex $(foreach v,tcb 1c msns mss mstx msr msn msnt sf nq
.PHONY: help-experimental help-prefixed
.PHONY: paper-clean periodcheck
-all: $(targ)
+all: periodcheck
ifeq ($(MAKECMDGOALS),clean)
else ifeq ($(MAKECMDGOALS),distclean)
@@ -611,7 +611,7 @@ ls-unused:
neatfreak: distclean
find . -name '*.pdf' | xargs rm -f
-periodcheck:
+periodcheck: $(targ)
utilities/periodcheck.sh
.SECONDEXPANSION:
--
2.17.1
^ permalink raw reply related [flat|nested] 15+ messages in thread* Re: [PATCH -perfbook v2 0/9] Add script to check period spacing
2021-04-27 22:32 ` Akira Yokosawa
@ 2021-04-27 22:52 ` Paul E. McKenney
2021-04-27 23:58 ` Akira Yokosawa
0 siblings, 1 reply; 15+ messages in thread
From: Paul E. McKenney @ 2021-04-27 22:52 UTC (permalink / raw)
To: Akira Yokosawa; +Cc: perfbook
On Wed, Apr 28, 2021 at 07:32:25AM +0900, Akira Yokosawa wrote:
> On Tue, 27 Apr 2021 08:51:26 -0700, Paul E. McKenney wrote:
> > On Wed, Apr 28, 2021 at 12:18:56AM +0900, Akira Yokosawa wrote:
> >> Hi Paul,
> >>
> >> This patch set adds a set of scripts to check proper annotation
> >> of periods to distinguish single and double spacing.
> >>
> >> Patch 1/9 adds a couple of annotations in-development version of
> >> the script had caught.
> >> Patches 2/9--5/9 add and improve the set of scripts.
> >> They are kept separate patches to show the history.
> >> Patches 6/9--9/9 are fixes in LaTeX sources to satisfy the script.
> >> There are quite a few sentences which end in the middle of
> >> input lines.
> >>
> >> After Patch 9/9 is applied, "make periodcheck" will be clean.
> >>
> >> I'm not saying the perl script is complete.
> >> There can still be false negatives I'm not aware of.
> >> False positives can happen when you add new contents.
> >
> > Queued and pushed, thank you!
> >
> > Would it make sense at some point to have "make periodcheck" happen
> > automatically during a normal build to catch addition of issues with
> > new content?
> >
> > Thanx, Paul
>
> Like this?
> Note that positive periodcheck doesn't cause a make error.
> It can be promoted to a real error later when we feel confident of
> the script.
>
> "make 2c" (or any explicit target) doesn't run the script.
This does work!
But I feel compelled to expose the ancient nature of my Makefile
knowledge and ask why not this single change?
all: $(targ) periodcheck
Thanx, Paul
> Thanks, Akira
>
> --------8<--------------------------
> From: Akira Yokosawa <akiyks@gmail.com>
> Date: Wed, 28 Apr 2021 07:26:05 +0900
> Subject: [PATCH] Auto run periodcheck on 'make'
>
> Run periodcheck on "make" and "make all".
> Now they are the same as "make periodcheck".
> "make periodcheck" builds your default target before the check.
>
> Suggested-by: Paul E. McKenney <paulmck@kernel.org>
> Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
> ---
> Makefile | 4 ++--
> 1 file changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/Makefile b/Makefile
> index ea264dc5..792fa285 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -194,7 +194,7 @@ BASE_DEPENDS := perfbook.tex $(foreach v,tcb 1c msns mss mstx msr msn msnt sf nq
> .PHONY: help-experimental help-prefixed
> .PHONY: paper-clean periodcheck
>
> -all: $(targ)
> +all: periodcheck
>
> ifeq ($(MAKECMDGOALS),clean)
> else ifeq ($(MAKECMDGOALS),distclean)
> @@ -611,7 +611,7 @@ ls-unused:
> neatfreak: distclean
> find . -name '*.pdf' | xargs rm -f
>
> -periodcheck:
> +periodcheck: $(targ)
> utilities/periodcheck.sh
>
> .SECONDEXPANSION:
> --
> 2.17.1
>
>
>
^ permalink raw reply [flat|nested] 15+ messages in thread
* Re: [PATCH -perfbook v2 0/9] Add script to check period spacing
2021-04-27 22:52 ` Paul E. McKenney
@ 2021-04-27 23:58 ` Akira Yokosawa
2021-04-28 0:10 ` Paul E. McKenney
0 siblings, 1 reply; 15+ messages in thread
From: Akira Yokosawa @ 2021-04-27 23:58 UTC (permalink / raw)
To: Paul E. McKenney; +Cc: perfbook, Akira Yokosawa
On Tue, 27 Apr 2021 15:52:42 -0700, Paul E. McKenney wrote:
> On Wed, Apr 28, 2021 at 07:32:25AM +0900, Akira Yokosawa wrote:
>> On Tue, 27 Apr 2021 08:51:26 -0700, Paul E. McKenney wrote:
>>> On Wed, Apr 28, 2021 at 12:18:56AM +0900, Akira Yokosawa wrote:
>>>> Hi Paul,
>>>>
>>>> This patch set adds a set of scripts to check proper annotation
>>>> of periods to distinguish single and double spacing.
>>>>
>>>> Patch 1/9 adds a couple of annotations in-development version of
>>>> the script had caught.
>>>> Patches 2/9--5/9 add and improve the set of scripts.
>>>> They are kept separate patches to show the history.
>>>> Patches 6/9--9/9 are fixes in LaTeX sources to satisfy the script.
>>>> There are quite a few sentences which end in the middle of
>>>> input lines.
>>>>
>>>> After Patch 9/9 is applied, "make periodcheck" will be clean.
>>>>
>>>> I'm not saying the perl script is complete.
>>>> There can still be false negatives I'm not aware of.
>>>> False positives can happen when you add new contents.
>>>
>>> Queued and pushed, thank you!
>>>
>>> Would it make sense at some point to have "make periodcheck" happen
>>> automatically during a normal build to catch addition of issues with
>>> new content?
>>>
>>> Thanx, Paul
>>
>> Like this?
>> Note that positive periodcheck doesn't cause a make error.
>> It can be promoted to a real error later when we feel confident of
>> the script.
>>
>> "make 2c" (or any explicit target) doesn't run the script.
>
> This does work!
>
> But I feel compelled to expose the ancient nature of my Makefile
> knowledge and ask why not this single change?
>
> all: $(targ) periodcheck
You might miss the output from periodcheck if you do
"make -jN"
, without the dependency of "periodcheck: $(targ)".
Thanks, Akira
>
> Thanx, Paul
>
>> Thanks, Akira
>>
>> --------8<--------------------------
>> From: Akira Yokosawa <akiyks@gmail.com>
>> Date: Wed, 28 Apr 2021 07:26:05 +0900
>> Subject: [PATCH] Auto run periodcheck on 'make'
>>
>> Run periodcheck on "make" and "make all".
>> Now they are the same as "make periodcheck".
>> "make periodcheck" builds your default target before the check.
>>
>> Suggested-by: Paul E. McKenney <paulmck@kernel.org>
>> Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
>> ---
>> Makefile | 4 ++--
>> 1 file changed, 2 insertions(+), 2 deletions(-)
>>
>> diff --git a/Makefile b/Makefile
>> index ea264dc5..792fa285 100644
>> --- a/Makefile
>> +++ b/Makefile
>> @@ -194,7 +194,7 @@ BASE_DEPENDS := perfbook.tex $(foreach v,tcb 1c msns mss mstx msr msn msnt sf nq
>> .PHONY: help-experimental help-prefixed
>> .PHONY: paper-clean periodcheck
>>
>> -all: $(targ)
>> +all: periodcheck
>>
>> ifeq ($(MAKECMDGOALS),clean)
>> else ifeq ($(MAKECMDGOALS),distclean)
>> @@ -611,7 +611,7 @@ ls-unused:
>> neatfreak: distclean
>> find . -name '*.pdf' | xargs rm -f
>>
>> -periodcheck:
>> +periodcheck: $(targ)
>> utilities/periodcheck.sh
>>
>> .SECONDEXPANSION:
>> --
>> 2.17.1
>>
>>
>>
^ permalink raw reply [flat|nested] 15+ messages in thread* Re: [PATCH -perfbook v2 0/9] Add script to check period spacing
2021-04-27 23:58 ` Akira Yokosawa
@ 2021-04-28 0:10 ` Paul E. McKenney
0 siblings, 0 replies; 15+ messages in thread
From: Paul E. McKenney @ 2021-04-28 0:10 UTC (permalink / raw)
To: Akira Yokosawa; +Cc: perfbook
On Wed, Apr 28, 2021 at 08:58:57AM +0900, Akira Yokosawa wrote:
> On Tue, 27 Apr 2021 15:52:42 -0700, Paul E. McKenney wrote:
> > On Wed, Apr 28, 2021 at 07:32:25AM +0900, Akira Yokosawa wrote:
> >> On Tue, 27 Apr 2021 08:51:26 -0700, Paul E. McKenney wrote:
> >>> On Wed, Apr 28, 2021 at 12:18:56AM +0900, Akira Yokosawa wrote:
> >>>> Hi Paul,
> >>>>
> >>>> This patch set adds a set of scripts to check proper annotation
> >>>> of periods to distinguish single and double spacing.
> >>>>
> >>>> Patch 1/9 adds a couple of annotations in-development version of
> >>>> the script had caught.
> >>>> Patches 2/9--5/9 add and improve the set of scripts.
> >>>> They are kept separate patches to show the history.
> >>>> Patches 6/9--9/9 are fixes in LaTeX sources to satisfy the script.
> >>>> There are quite a few sentences which end in the middle of
> >>>> input lines.
> >>>>
> >>>> After Patch 9/9 is applied, "make periodcheck" will be clean.
> >>>>
> >>>> I'm not saying the perl script is complete.
> >>>> There can still be false negatives I'm not aware of.
> >>>> False positives can happen when you add new contents.
> >>>
> >>> Queued and pushed, thank you!
> >>>
> >>> Would it make sense at some point to have "make periodcheck" happen
> >>> automatically during a normal build to catch addition of issues with
> >>> new content?
> >>>
> >>> Thanx, Paul
> >>
> >> Like this?
> >> Note that positive periodcheck doesn't cause a make error.
> >> It can be promoted to a real error later when we feel confident of
> >> the script.
> >>
> >> "make 2c" (or any explicit target) doesn't run the script.
> >
> > This does work!
> >
> > But I feel compelled to expose the ancient nature of my Makefile
> > knowledge and ask why not this single change?
> >
> > all: $(targ) periodcheck
>
> You might miss the output from periodcheck if you do
>
> "make -jN"
>
> , without the dependency of "periodcheck: $(targ)".
Excellent point, thank you!
Thanx, Paul
> Thanks, Akira
>
> >
> > Thanx, Paul
> >
> >> Thanks, Akira
> >>
> >> --------8<--------------------------
> >> From: Akira Yokosawa <akiyks@gmail.com>
> >> Date: Wed, 28 Apr 2021 07:26:05 +0900
> >> Subject: [PATCH] Auto run periodcheck on 'make'
> >>
> >> Run periodcheck on "make" and "make all".
> >> Now they are the same as "make periodcheck".
> >> "make periodcheck" builds your default target before the check.
> >>
> >> Suggested-by: Paul E. McKenney <paulmck@kernel.org>
> >> Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
> >> ---
> >> Makefile | 4 ++--
> >> 1 file changed, 2 insertions(+), 2 deletions(-)
> >>
> >> diff --git a/Makefile b/Makefile
> >> index ea264dc5..792fa285 100644
> >> --- a/Makefile
> >> +++ b/Makefile
> >> @@ -194,7 +194,7 @@ BASE_DEPENDS := perfbook.tex $(foreach v,tcb 1c msns mss mstx msr msn msnt sf nq
> >> .PHONY: help-experimental help-prefixed
> >> .PHONY: paper-clean periodcheck
> >>
> >> -all: $(targ)
> >> +all: periodcheck
> >>
> >> ifeq ($(MAKECMDGOALS),clean)
> >> else ifeq ($(MAKECMDGOALS),distclean)
> >> @@ -611,7 +611,7 @@ ls-unused:
> >> neatfreak: distclean
> >> find . -name '*.pdf' | xargs rm -f
> >>
> >> -periodcheck:
> >> +periodcheck: $(targ)
> >> utilities/periodcheck.sh
> >>
> >> .SECONDEXPANSION:
> >> --
> >> 2.17.1
> >>
> >>
> >>
^ permalink raw reply [flat|nested] 15+ messages in thread