[PATCH -perfbook 1/3] intro, together: Promote section-opening QQzs to 'essential'

[PATCH -perfbook 1/3] intro, together: Promote section-opening QQzs to 'essential'

[Akira Yokosawa]

In "nq" builds, section-opening QQzs can result in headings which
look like "widow" ones accompanied by small boxes of "QQ x.x".

When you start a section by a QQz, it is likely an essential one
and would better be presented even in "nq" builds.

Promote such two QQzs to "essential" ones.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
 intro/intro.tex       | 6 +++---
 together/applyrcu.tex | 6 +++---
 2 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/intro/intro.tex b/intro/intro.tex
index 635173e1..e39ea652 100644
--- a/intro/intro.tex
+++ b/intro/intro.tex
@@ -416,12 +416,12 @@ sequential case when analyzing the performance of parallel algorithms.
 \subsection{Productivity}
 \label{sec:intro:Productivity}
 
-\QuickQuiz{
+\EQuickQuiz{
 	Why all this prattling on about non-technical issues???
 	And not just \emph{any} non-technical issue, but \emph{productivity}
 	of all things?
 	Who cares?
-}\QuickQuizAnswer{
+}\EQuickQuizAnswer{
 	If you are a pure hobbyist, perhaps you don't need to care.
 	But even pure hobbyists will often care about how much they
 	can get done, and how quickly.
@@ -435,7 +435,7 @@ sequential case when analyzing the performance of parallel algorithms.
 
 	Besides, if you \emph{really} didn't care about productivity,
 	you would be doing it by hand rather than using a computer!
-}\QuickQuizEnd
+}\EQuickQuizEnd
 
 \IX{Productivity} has been becoming increasingly important in recent decades.
 To see this, consider that the price of early computers was tens
diff --git a/together/applyrcu.tex b/together/applyrcu.tex
index e3a0d2fe..9aef3879 100644
--- a/together/applyrcu.tex
+++ b/together/applyrcu.tex
@@ -196,13 +196,13 @@ references.
 
 \subsubsection{Discussion}
 
-\QuickQuiz{
+\EQuickQuiz{
 	Wow!
 	\Cref{lst:together:RCU and Per-Thread Statistical Counters}
 	contains 70 lines of code, compared to only 42 in
 	\cref{lst:count:Per-Thread Statistical Counters}.
 	Is this extra complexity really worth it?
-}\QuickQuizAnswer{
+}\EQuickQuizAnswer{
 	This of course needs to be decided on a case-by-case basis.
 	If you need an implementation of \co{read_count()} that
 	scales linearly, then the lock-based implementation shown in
@@ -224,7 +224,7 @@ references.
 	with all the scalability and performance benefits of the
 	implementation shown in
 	\cref{lst:together:RCU and Per-Thread Statistical Counters}!
-}\QuickQuizEnd
+}\EQuickQuizEnd
 
 Use of RCU enables exiting threads to wait until other threads are
 guaranteed to be done using the exiting threads' \co{__thread} variables.

base-commit: e4815ca92805056635d98935562ced9e41fd0fb4
-- 
2.17.1

[PATCH -perfbook 2/3] defer, together: Group consecutive QQzs

[Akira Yokosawa]

These consecutive pairs of plain QQzs should be grouped by the
\QuickQuizSeries{ ... } construct.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
 defer/rcuusage.tex   | 14 ++++++++------
 together/seqlock.tex | 14 ++++++++------
 2 files changed, 16 insertions(+), 12 deletions(-)

diff --git a/defer/rcuusage.tex b/defer/rcuusage.tex
index 2fb517c2..7a624e4c 100644
--- a/defer/rcuusage.tex
+++ b/defer/rcuusage.tex
@@ -506,13 +506,14 @@ run concurrently with \co{do_maint()} to complete, and finally
 \clnref{toquick} sets the \co{be_careful} flag back to \co{false}.
 \end{fcvref}
 
-\QuickQuiz{
+\QuickQuizSeries{%
+\QuickQuizB{
 	What is the point of the second call to \co{synchronize_rcu()}
 	in function
 	\co{maint()} in \cref{lst:defer:Phased State Change for Maintenance Operations}?
 	Isn't it OK for any \co{cco()} invocations in the clean-up
 	phase to invoke either \co{cco_carefully()} or \co{cco_quickly()}?
-}\QuickQuizAnswer{
+}\QuickQuizAnswerB{
 	The problem is that there is no ordering between the \co{cco()}
 	function's load from \co{be_careful} and any memory loads
 	executed by the \co{cco_quickly()} function.
@@ -525,13 +526,13 @@ run concurrently with \co{do_maint()} to complete, and finally
 	\co{READ_ONCE()} to \co{smp_load_acquire()} and the
 	\co{WRITE_ONCE()} to \co{smp_store_release()}, thus restoring
 	the needed ordering.
-}\QuickQuizEnd
+}\QuickQuizEndB
 
-\QuickQuiz{
+\QuickQuizE{
 	How can you be sure that the code shown in
 	\co{maint()} in \cref{lst:defer:Phased State Change for Maintenance Operations}
 	really works?\@
-}\QuickQuizAnswer{
+}\QuickQuizAnswerE{
 	By one popular school of thought, you cannot.
 
 	But in this case, those willing to jump ahead to
@@ -543,7 +544,8 @@ run concurrently with \co{do_maint()} to complete, and finally
 	\path{C-RCU-phased-state-change-2.litmus}).
 	These tests could be argued to demonstrate that this code
 	and a variant of it really do work.
-}\QuickQuizEnd
+}\QuickQuizEndE
+}% End of \QuickQuizSeries
 
 Phased state change allows frequent operations to use light-weight
 checks, without the need for expensive lock acquisitions or atomic
diff --git a/together/seqlock.tex b/together/seqlock.tex
index b8acbe3d..42eb8faa 100644
--- a/together/seqlock.tex
+++ b/together/seqlock.tex
@@ -221,11 +221,12 @@ Any reader succeeding in looking up the new name is guaranteed that
 any subsequent lookup of the old name will fail, perhaps after a series
 of retries.
 
-\QuickQuiz{
+\QuickQuizSeries{%
+\QuickQuizB{
 	Is it possible to write-acquire the sequence lock on
 	the new element before it is inserted instead of acquiring
 	that of the old element before it is removed?
-}\QuickQuizAnswer{
+}\QuickQuizAnswerB{
 	Yes, and the details are left as an exercise to the reader.
 
 	The term \emph{tombstone} is sometimes used to refer to the
@@ -233,11 +234,11 @@ of retries.
 	Similarly, the term \emph{birthstone} is sometimes used to refer
 	to the element with the new name while its sequence lock is
 	still held.
-}\QuickQuizEnd
+}\QuickQuizEndB
 
-\QuickQuiz{
+\QuickQuizE{
 	Is it possible to avoid the global lock?
-}\QuickQuizAnswer{
+}\QuickQuizAnswerE{
 	Yes, and one way to do this would be to use per-hash-chain locks.
 	The updater could acquire lock(s) corresponding to both the old
 	and the new element, acquiring them in address order.
@@ -247,7 +248,8 @@ of retries.
 	This complexity can be worthwhile if rename operations are
 	frequent, and of course can allow rename operations to execute
 	concurrently.
-}\QuickQuizEnd
+}\QuickQuizEndE
+}% End of \QuickQuizSeries
 
 It is of course possible to instead implement this procedure somewhat
 more efficiently using simple flags.
-- 
2.17.1

[PATCH -perfbook 3/3] cleverefcheck.pl: Add patterns to catch QQz positioning issues

[Akira Yokosawa]

Add patterns in cleverefcheck.pl to catch:

  - A plain QQz or grouped QQzs at the beginning of a section
  - Consecutive QQzs not properly grouped

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
 utilities/cleverefcheck.pl | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/utilities/cleverefcheck.pl b/utilities/cleverefcheck.pl
index 6e9a59e8..d92de5ac 100755
--- a/utilities/cleverefcheck.pl
+++ b/utilities/cleverefcheck.pl
@@ -28,12 +28,14 @@ my $acr_ptn = qr/(^|\s+)[aA]cr[^\s\{]*{/ ;
 my $heading_ptn = qr/(\\chapter|\\section|\\subsection|\\subsubsection)/ ;
 my $listing_ptn = qr/\\begin\{(listing|Verbatim)/ ;
 my $qqa_ptn = qr/\\E?QuickQuizAnswer[BEM]?/ ;
+my $qqe_ptn = qr/\}\\QuickQuizEnd\s*(%.*)?$/ ;
 my $epig_ptn = qr/\\[Ee]pigraph/ ;
 my $in_footnote = 0 ;
 my $footnote_save = 0;
 my $after_heading = 0;
 my $after_qqa = 0;
 my $after_epig = 0;
+my $after_qqe = 0;
 
 sub check_line {
     my $raw_line = $line;
@@ -121,6 +123,10 @@ sub check_line {
 	    $after_heading = 0 ;
 	    $after_epig = 0 ;  # after epigraph or not does not matter for listing
 	}
+	if ($line =~ /\\QuickQuiz\{/ || $line =~ /\\QuickQiuzSeries\{/) {
+	    print $ARGV[0], ':', $line_num, ':', $raw_line, "^^^ Section opening QQz ^^^\n";
+	    $after_heading = 0 ;
+	}
     }
     if ($after_qqa) {
 	if ($line =~ /^\s*$/) {
@@ -134,6 +140,15 @@ sub check_line {
 	    $after_qqa = 0;
 	}
     }
+    if ($after_qqe) {
+	if ($line =~ /\\QuickQuiz\{/) {
+	    print $ARGV[0], ':', $line_num, ':', $raw_line, "^^^ Consecutive QQz ^^^\n";
+	    $after_qqe = 0;
+	}
+	if ($line !~ /^\s*$/) {  # non-empty line ends after qqe status
+	    $after_qqe = 0;
+	}
+    }
     if ($after_epig) {
 	if ($line =~ /^\s*$/) {  # empty line ends epigraph
 	    $after_epig -= 1 ;
@@ -182,6 +197,9 @@ sub check_line {
     if ($line =~ /$qqa_ptn/) {
 	$after_qqa = 1 ;
     }
+    if ($line =~ /$qqe_ptn/) {
+	$after_qqe = 1 ;
+    }
     if ($line =~ /$epig_ptn/ && $ARGV[0] !~ /glossary\.tex/) { # exempt glossary.tex
 	$after_epig = 2 ;
     }
-- 
2.17.1

Re: [PATCH -perfbook 3/3] cleverefcheck.pl: Add patterns to catch QQz positioning issues

[Akira Yokosawa]

On Thu, 10 Feb 2022 00:12:23 +0900,
Akira Yokosawa wrote:
> Add patterns in cleverefcheck.pl to catch:
> 
>   - A plain QQz or grouped QQzs at the beginning of a section
>   - Consecutive QQzs not properly grouped
> 
> Signed-off-by: Akira Yokosawa <akiyks@gmail.com>

Paul,

You can see how the added pattern works by applying only 3/3
on current master e4815ca92805 ("memorder: Fix typos"), and
run "make punctcheck".

It will complain QQzs Patches 1/3 and 2/3 fix.

        Thanks, Akira

> ---
>  utilities/cleverefcheck.pl | 18 ++++++++++++++++++
>  1 file changed, 18 insertions(+)
> 
> diff --git a/utilities/cleverefcheck.pl b/utilities/cleverefcheck.pl
> index 6e9a59e8..d92de5ac 100755
> --- a/utilities/cleverefcheck.pl
> +++ b/utilities/cleverefcheck.pl
[...]

Re: [PATCH -perfbook 1/3] intro, together: Promote section-opening QQzs to 'essential'

[Paul E. McKenney]

On Thu, Feb 10, 2022 at 12:06:58AM +0900, Akira Yokosawa wrote:
> In "nq" builds, section-opening QQzs can result in headings which
> look like "widow" ones accompanied by small boxes of "QQ x.x".
> 
> When you start a section by a QQz, it is likely an essential one
> and would better be presented even in "nq" builds.
> 
> Promote such two QQzs to "essential" ones.
> 
> Signed-off-by: Akira Yokosawa <akiyks@gmail.com>

Good points!  I queued and pushed the series, thank you!

							Thanx, Paul

> ---
>  intro/intro.tex       | 6 +++---
>  together/applyrcu.tex | 6 +++---
>  2 files changed, 6 insertions(+), 6 deletions(-)
> 
> diff --git a/intro/intro.tex b/intro/intro.tex
> index 635173e1..e39ea652 100644
> --- a/intro/intro.tex
> +++ b/intro/intro.tex
> @@ -416,12 +416,12 @@ sequential case when analyzing the performance of parallel algorithms.
>  \subsection{Productivity}
>  \label{sec:intro:Productivity}
>  
> -\QuickQuiz{
> +\EQuickQuiz{
>  	Why all this prattling on about non-technical issues???
>  	And not just \emph{any} non-technical issue, but \emph{productivity}
>  	of all things?
>  	Who cares?
> -}\QuickQuizAnswer{
> +}\EQuickQuizAnswer{
>  	If you are a pure hobbyist, perhaps you don't need to care.
>  	But even pure hobbyists will often care about how much they
>  	can get done, and how quickly.
> @@ -435,7 +435,7 @@ sequential case when analyzing the performance of parallel algorithms.
>  
>  	Besides, if you \emph{really} didn't care about productivity,
>  	you would be doing it by hand rather than using a computer!
> -}\QuickQuizEnd
> +}\EQuickQuizEnd
>  
>  \IX{Productivity} has been becoming increasingly important in recent decades.
>  To see this, consider that the price of early computers was tens
> diff --git a/together/applyrcu.tex b/together/applyrcu.tex
> index e3a0d2fe..9aef3879 100644
> --- a/together/applyrcu.tex
> +++ b/together/applyrcu.tex
> @@ -196,13 +196,13 @@ references.
>  
>  \subsubsection{Discussion}
>  
> -\QuickQuiz{
> +\EQuickQuiz{
>  	Wow!
>  	\Cref{lst:together:RCU and Per-Thread Statistical Counters}
>  	contains 70 lines of code, compared to only 42 in
>  	\cref{lst:count:Per-Thread Statistical Counters}.
>  	Is this extra complexity really worth it?
> -}\QuickQuizAnswer{
> +}\EQuickQuizAnswer{
>  	This of course needs to be decided on a case-by-case basis.
>  	If you need an implementation of \co{read_count()} that
>  	scales linearly, then the lock-based implementation shown in
> @@ -224,7 +224,7 @@ references.
>  	with all the scalability and performance benefits of the
>  	implementation shown in
>  	\cref{lst:together:RCU and Per-Thread Statistical Counters}!
> -}\QuickQuizEnd
> +}\EQuickQuizEnd
>  
>  Use of RCU enables exiting threads to wait until other threads are
>  guaranteed to be done using the exiting threads' \co{__thread} variables.
> 
> base-commit: e4815ca92805056635d98935562ced9e41fd0fb4
> -- 
> 2.17.1
>