[PATCH 00/13] Minor fixes for defer/

[PATCH 00/13] Minor fixes for defer/

[SeongJae Park]

From: SeongJae Park <sj38.park@gmail.com>

This patchset contains minor fixes for defer/ that found during the
Korean translation[1] of it.

[1] https://github.com/sjp38/perfbook-ko_KR

SeongJae Park (13):
  defer/rcuintro: Clearly point the QSBR described section
  defer/rcufundamental: Add non-breaking spaces
  defer/rcuapi: Add missed unbreakable spaces
  defer/rcuapi: Use \co{} for boolean return value
  defer/seqlock: Use \co{} for boolean return value
  defer/rcuusage: Call paragraphs paragraphs, not sections
  defer/rcuusage: Provide the reference to synchronous RCU update-side
    primitives
  defer/rcuusage: Add a missed unbreakable space
  defer/rcuusage: Add missing '()' for 'rcu_dereference()'
  defer/rcuusage: Fix wrong function name: s/timer_stop/nmi_stop/
  defer/rcurelated: Remove unopen closing parentheses
  defer/whichtochoose: Fix a wrongly positioned unbreakable space
  defer/whichtochoose: Remove an unnecessary space.

 defer/rcuapi.tex         | 10 +++++-----
 defer/rcufundamental.tex |  6 +++---
 defer/rcuintro.tex       |  3 ++-
 defer/rcurelated.tex     |  2 +-
 defer/rcuusage.tex       | 14 ++++++++------
 defer/seqlock.tex        |  4 ++--
 defer/whichtochoose.tex  |  4 ++--
 7 files changed, 23 insertions(+), 20 deletions(-)

-- 
2.17.1

[PATCH 01/13] defer/rcuintro: Clearly point the QSBR described section

[SeongJae Park]

From: SeongJae Park <sj38.park@gmail.com>

'Toy Implementation' section of 'defer/rcuintro' says QSBR is described
in the section, but it's actually explained in detail in its previous
section, 'Waiting for Readers'.  This commit updates the sentence to
point the sepcific section for a better reference.

Signed-off-by: SeongJae Park <sj38.park@gmail.com>
---
 defer/rcuintro.tex | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/defer/rcuintro.tex b/defer/rcuintro.tex
index 2f4e7ee3..7007058b 100644
--- a/defer/rcuintro.tex
+++ b/defer/rcuintro.tex
@@ -621,7 +621,8 @@ Referring back to
 note that \co{route_lock} is used to synchronize between concurrent updaters
 invoking \co{ins_route()} and \co{del_route()}.
 However, this lock is not acquired by readers invoking \co{access_route()}:
-Readers are instead protected by the QSBR techniques described in this section.
+Readers are instead protected by the QSBR techniques described in
+\cref{sec:defer:Waiting for Readers}.
 
 Note that \co{ins_route()} simply returns the old value of \co{gptr}, which
 \cref{fig:defer:Insertion With Concurrent Readers} assumed would
-- 
2.17.1

[PATCH 02/13] defer/rcufundamental: Add non-breaking spaces

[SeongJae Park]

From: SeongJae Park <sj38.park@gmail.com>

Linked list example in rcufundamental.tex misses non-breaking spaces
between 'and' and a data item.  Add it for better compilation of the
book.

Signed-off-by: SeongJae Park <sj38.park@gmail.com>
---
 defer/rcufundamental.tex | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/defer/rcufundamental.tex b/defer/rcufundamental.tex
index 39b2f7ff..5e7d6675 100644
--- a/defer/rcufundamental.tex
+++ b/defer/rcufundamental.tex
@@ -153,7 +153,7 @@ structures without disrupting concurrent readers.
 	items from a linked list while a reader is iterating over that
 	same list.
 	Specifically, suppose that a list initially contains elements
-	A, B, and C, and that an updater removes element A and then
+	A, B, and~C, and that an updater removes element A and then
 	adds a new element D at the end of the list.
 	The reader might well see \{A, B, C, D\}, when that sequence of
 	elements never actually ever existed!
@@ -163,8 +163,8 @@ structures without disrupting concurrent readers.
 	In the universe where an iterating reader is only required to
 	traverse elements that were present throughout the full duration
 	of the iteration.
-	In the example, that would be elements B and C\@.
-	Because elements A and D were each present for only part of the
+	In the example, that would be elements B and~C\@.
+	Because elements A and~D were each present for only part of the
 	iteration, the reader is permitted to iterate over them, but not
 	obliged to.
 	Note that this supports the common case where the reader is simply
-- 
2.17.1

[PATCH 03/13] defer/rcuapi: Add missed unbreakable spaces

[SeongJae Park]

From: SeongJae Park <sj38.park@gmail.com>

Add missed unbreakable spaces in defer/rcuapi.tex.

Signed-off-by: SeongJae Park <sj38.park@gmail.com>
---
 defer/rcuapi.tex | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/defer/rcuapi.tex b/defer/rcuapi.tex
index 8ee54866..425c64ff 100644
--- a/defer/rcuapi.tex
+++ b/defer/rcuapi.tex
@@ -948,8 +948,8 @@ element in the middle of the list having multiple fields is atomically
 updated, so that a given reader sees either the old set of values or
 the new set of values, but not a mixture of the two sets.
 For example, each node of a linked list might have integer fields
-\co{->a}, \co{->b}, and \co{->c}, and it might be necessary to update
-a given node's fields from 5, 6, and 7 to 5, 2, and 3, respectively.
+\co{->a}, \co{->b}, and~\co{->c}, and it might be necessary to update
+a given node's fields from 5, 6, and~7 to 5, 2, and~3, respectively.
 
 The code implementing this atomic update is straightforward:
 
@@ -980,7 +980,7 @@ The following discussion walks through this code, using
 \cref{fig:defer:RCU Replacement in Linked List} to illustrate
 the state changes.
 The triples in each element represent the values of fields \co{->a},
-\co{->b}, and \co{->c}, respectively.
+\co{->b}, and~\co{->c}, respectively.
 The red-shaded elements might be referenced by readers,
 and because readers do not synchronize directly with updaters,
 readers might run concurrently with this entire replacement process.
-- 
2.17.1

[PATCH 04/13] defer/rcuapi: Use \co{} for boolean return value

[SeongJae Park]

From: SeongJae Park <sj38.park@gmail.com>

\co{} is used for some boolean return value and not for some other case.
To make it consistent, use \co{} for all.

Signed-off-by: SeongJae Park <sj38.park@gmail.com>
---
 defer/rcuapi.tex | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/defer/rcuapi.tex b/defer/rcuapi.tex
index 425c64ff..9ac2d26c 100644
--- a/defer/rcuapi.tex
+++ b/defer/rcuapi.tex
@@ -785,7 +785,7 @@ Should a reader encounter a \co{NULL} pointer not matching the index of
 the bucket it started from, that reader knows that an element it was
 traversing was moved to some other bucket during the traversal, taking
 that reader with it.
-The reader can use the \apik{is_a_nulls()} function (which returns true
+The reader can use the \apik{is_a_nulls()} function (which returns \co{true}
 if passed an \co{hlist_nulls} \co{NULL} pointer) to determine when
 it reaches the end of a list, and the \apik{get_nulls_value()} function
 (which returns its argument's \co{NULL}-pointer identifier) to fetch
@@ -1156,7 +1156,7 @@ type of RCU read-side critical section.
 
 Because \co{rcu_read_lock()} cannot be used from the idle loop,
 and because energy-efficiency concerns have caused the idle loop
-to become quite ornate, \apik{rcu_is_watching()} returns true if
+to become quite ornate, \apik{rcu_is_watching()} returns \co{true} if
 invoked in a context where use of \co{rcu_read_lock()} is legal.
 Note again that \co{srcu_read_lock()} may be used from idle and
 even offline CPUs, which means that \co{rcu_is_watching()} does not
-- 
2.17.1

[PATCH 05/13] defer/seqlock: Use \co{} for boolean return value

[SeongJae Park]

From: SeongJae Park <sj38.park@gmail.com>

\co{} is used for some boolean return values and not for some other
cases.  To make it consistent, this commit makes it uses \co{} for all.

Signed-off-by: SeongJae Park <sj38.park@gmail.com>
---
 defer/seqlock.tex | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/defer/seqlock.tex b/defer/seqlock.tex
index da1d19ec..f435a1af 100644
--- a/defer/seqlock.tex
+++ b/defer/seqlock.tex
@@ -144,14 +144,14 @@ will pass to a later call to \co{read_seqretry()}.
 }\QuickQuizEnd
 
 \begin{fcvref}[ln:defer:seqlock:impl:read_seqretry]
-\Clnrefrange{b}{e} show \co{read_seqretry()}, which returns true if there
+\Clnrefrange{b}{e} show \co{read_seqretry()}, which returns \co{true} if there
 was at least one writer since the time of the corresponding
 call to \co{read_seqbegin()}.
 \Clnref{mb} orders the caller's prior critical section before \clnref{fetch}'s
 fetch of the new snapshot of the sequence counter.
 \Clnref{ret} checks whether the sequence counter has changed,
 in other words, whether there has been at least one writer, and returns
-true if so.
+\co{true} if so.
 \end{fcvref}
 
 \QuickQuizSeries{%
-- 
2.17.1

[PATCH 06/13] defer/rcuusage: Call paragraphs paragraphs, not sections

[SeongJae Park]

From: SeongJae Park <sj38.park@gmail.com>

Some sentences in rcuusage calls following paragraphs as sections.  Fix
it to minimize any confusion.

Signed-off-by: SeongJae Park <sj38.park@gmail.com>
---
 defer/rcuusage.tex | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/defer/rcuusage.tex b/defer/rcuusage.tex
index 9da0e04c..8c45093f 100644
--- a/defer/rcuusage.tex
+++ b/defer/rcuusage.tex
@@ -946,7 +946,7 @@ There are, of course, limitations to RCU, including the fact that
 readers and updaters run concurrently, that low-priority RCU readers
 can block high-priority threads waiting for a grace period to elapse,
 and that grace-period latencies can extend for many milliseconds.
-These advantages and limitations are discussed in the following sections.
+These advantages and limitations are discussed in the following paragraphs.
 
 \paragraph{Performance}
 
@@ -1162,7 +1162,7 @@ systems are no longer uncommon and that a number of system calls (and
 thus any RCU read-side critical sections that they contain) complete
 within microseconds.
 
-In addition, as is discussed in the next section,
+In addition, as is discussed in the next paragraph,
 RCU read-side primitives are almost entirely deadlock-immune.
 
 
-- 
2.17.1

[PATCH 07/13] defer/rcuusage: Provide the reference to synchronous RCU update-side primitives

[SeongJae Park]

From: SeongJae Park <sj38.park@gmail.com>

'Deadlock Immunity' paragraph prohibits synchronous RCU update-side
primitives within RCU read-side critical section.  This means those in
'RCU Wait-to-Finish APIs' table, but someone might think those as
general RCU update-side primitives like 'rcu_assign_pointer()'.  To make
it clear, provide the reference to the table.

Signed-off-by: SeongJae Park <sj38.park@gmail.com>
---
 defer/rcuusage.tex | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/defer/rcuusage.tex b/defer/rcuusage.tex
index 8c45093f..18abf340 100644
--- a/defer/rcuusage.tex
+++ b/defer/rcuusage.tex
@@ -1209,7 +1209,9 @@ rcu_read_unlock();
 	result of the grace period completing.
 	Plus Linux kernel's lockdep facility will yell at you.
 
-	In short, do not invoke synchronous RCU update-side primitives
+	In short, do not invoke synchronous RCU update-side primitives, which
+	are listed in
+	\cref{tab:defer:RCU Wait-to-Finish APIs},
 	from within an RCU read-side critical section.
 
 	In addition, within the Linux kernel, RCU uses the scheduler
-- 
2.17.1

[PATCH 08/13] defer/rcuusage: Add a missed unbreakable space

[SeongJae Park]

From: SeongJae Park <sj38.park@gmail.com>

Signed-off-by: SeongJae Park <sj38.park@gmail.com>
---
 defer/rcuusage.tex | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/defer/rcuusage.tex b/defer/rcuusage.tex
index 18abf340..ba13bd96 100644
--- a/defer/rcuusage.tex
+++ b/defer/rcuusage.tex
@@ -689,7 +689,7 @@ the slab allocator's deferred reclamation specified by the
 Gamsa et al.~\cite{Gamsa99}
 discuss \IXpl{existence guarantee} and describe how a mechanism
 resembling RCU can be used to provide these existence guarantees
-(see Section~5 on page 7 of the PDF), and
+(see Section~5 on page~7 of the PDF), and
 \cref{sec:locking:Lock-Based Existence Guarantees}
 discusses how to guarantee existence via locking, along with the
 ensuing disadvantages of doing so.
-- 
2.17.1

[PATCH 09/13] defer/rcuusage: Add missing '()' for 'rcu_dereference()'

[SeongJae Park]

From: SeongJae Park <sj38.park@gmail.com>

A sentence is missing '()' for 'rcu_dereference()'.  Add it.

Signed-off-by: SeongJae Park <sj38.park@gmail.com>
---
 defer/rcuusage.tex | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/defer/rcuusage.tex b/defer/rcuusage.tex
index ba13bd96..1dc4c2ca 100644
--- a/defer/rcuusage.tex
+++ b/defer/rcuusage.tex
@@ -645,7 +645,7 @@ It is important to note that \co{SLAB_TYPESAFE_BY_RCU} will
 prevent \co{kmem_cache_alloc()} from immediately reallocating
 memory that was just now freed via \co{kmem_cache_free()}!
 In fact, the \co{SLAB_TYPESAFE_BY_RCU}-protected data structure
-just returned by \co{rcu_dereference} might be freed and reallocated
+just returned by \co{rcu_dereference()} might be freed and reallocated
 an arbitrarily large number of times, even when under the protection
 of \co{rcu_read_lock()}.
 Instead, \co{SLAB_TYPESAFE_BY_RCU} operates by preventing
-- 
2.17.1

[PATCH 10/13] defer/rcuusage: Fix wrong function name: s/timer_stop/nmi_stop/

[SeongJae Park]

From: SeongJae Park <sj38.park@gmail.com>

A sentence in 'RCU is a Way of Waiting for Things to Finish' section is
calling 'nmi_stop()' as 'timer_stop()'.  Fix it.

Signed-off-by: SeongJae Park <sj38.park@gmail.com>
---
 defer/rcuusage.tex | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/defer/rcuusage.tex b/defer/rcuusage.tex
index 1dc4c2ca..372a508d 100644
--- a/defer/rcuusage.tex
+++ b/defer/rcuusage.tex
@@ -272,7 +272,7 @@ The basic form of such ``Pure RCU'' designs is as follows:
 
 The remainder of this section presents example code adapted from
 the Linux kernel.
-In this example, the \co{timer_stop()} function in the now-defunct
+In this example, the \co{nmi_stop()} function in the now-defunct
 oprofile facility uses \co{synchronize_sched()} to ensure that all
 in-flight NMI notifications have completed before freeing the associated
 resources.
-- 
2.17.1

[PATCH 11/13] defer/rcurelated: Remove unopen closing parentheses

[SeongJae Park]

From: SeongJae Park <sj38.park@gmail.com>

A sentence in rcurelated.tex has a closing parentheses whilt it has no
counter opening parentheses.  Probably a typo, so remove it.

Signed-off-by: SeongJae Park <sj38.park@gmail.com>
---
 defer/rcurelated.tex | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/defer/rcurelated.tex b/defer/rcurelated.tex
index 1ca25d9e..190c8456 100644
--- a/defer/rcurelated.tex
+++ b/defer/rcurelated.tex
@@ -111,7 +111,7 @@ Unfortunately, this implementation achieves linearizability by incurring
 the full latency of grace-period waits while holding locks, which degrades
 scalability of update-only workloads.
 One way around this problem is to abandon
-linearizability~\cite{AndreasHaas2012FIFOisnt,PaulEMcKennneyAtomicTreeN4037}),
+linearizability~\cite{AndreasHaas2012FIFOisnt,PaulEMcKennneyAtomicTreeN4037},
 however, Arbel and Attiya instead created an RCU variant that reduces
 low-end grace-period latency.
 Of course, nothing comes for free, and this RCU variant appears to hit
-- 
2.17.1

[PATCH 12/13] defer/whichtochoose: Fix a wrongly positioned unbreakable space

[SeongJae Park]

From: SeongJae Park <sj38.park@gmail.com>

There is a sentence mistakenly positioning an unbreakable space in the
middle of sentence.  Fix it.

Signed-off-by: SeongJae Park <sj38.park@gmail.com>
---
 defer/whichtochoose.tex | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/defer/whichtochoose.tex b/defer/whichtochoose.tex
index 489299a7..846c1ea1 100644
--- a/defer/whichtochoose.tex
+++ b/defer/whichtochoose.tex
@@ -347,7 +347,7 @@ in that order, and the following series of events:
 
 \begin{enumerate}
 \item	A reader acquires a reference to object~B.
-\item	An updater removes~object B, but refrains from freeing it because
+\item	An updater removes object~B, but refrains from freeing it because
 	the reader holds a reference.
 	The list now contains objects~A, C, and~D, and
 	object~B's \co{->next} pointer is set to \co{HAZPTR_POISON}.
-- 
2.17.1

[PATCH 13/13] defer/whichtochoose: Remove an unnecessary space.

[SeongJae Park]

From: SeongJae Park <sj38.park@gmail.com>

Signed-off-by: SeongJae Park <sj38.park@gmail.com>
---
 defer/whichtochoose.tex | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/defer/whichtochoose.tex b/defer/whichtochoose.tex
index 846c1ea1..dad3217a 100644
--- a/defer/whichtochoose.tex
+++ b/defer/whichtochoose.tex
@@ -378,7 +378,7 @@ it must avoid freeing any object reachable by a given
 RCU reader until that reader completes.
 RCU therefore has an unbounded memory footprint, at least unless updates
 are throttled.
-In contrast, reference counting and hazard pointers need to  retain only
+In contrast, reference counting and hazard pointers need to retain only
 those data elements actually referenced by concurrent readers.
 
 This tension between memory footprint and acquisition
-- 
2.17.1

Re: [PATCH 00/13] Minor fixes for defer/

[Paul E. McKenney]

On Thu, Nov 24, 2022 at 10:57:49AM -0800, SeongJae Park wrote:
> From: SeongJae Park <sj38.park@gmail.com>
> 
> This patchset contains minor fixes for defer/ that found during the
> Korean translation[1] of it.
> 
> [1] https://github.com/sjp38/perfbook-ko_KR

Good catches, thank you!!!  Queued and pushed.

And a happy Thanksgiving weekend to you, assuming that you are still
in Seattle.  ;-)

							Thanx, Paul

> SeongJae Park (13):
>   defer/rcuintro: Clearly point the QSBR described section
>   defer/rcufundamental: Add non-breaking spaces
>   defer/rcuapi: Add missed unbreakable spaces
>   defer/rcuapi: Use \co{} for boolean return value
>   defer/seqlock: Use \co{} for boolean return value
>   defer/rcuusage: Call paragraphs paragraphs, not sections
>   defer/rcuusage: Provide the reference to synchronous RCU update-side
>     primitives
>   defer/rcuusage: Add a missed unbreakable space
>   defer/rcuusage: Add missing '()' for 'rcu_dereference()'
>   defer/rcuusage: Fix wrong function name: s/timer_stop/nmi_stop/
>   defer/rcurelated: Remove unopen closing parentheses
>   defer/whichtochoose: Fix a wrongly positioned unbreakable space
>   defer/whichtochoose: Remove an unnecessary space.
> 
>  defer/rcuapi.tex         | 10 +++++-----
>  defer/rcufundamental.tex |  6 +++---
>  defer/rcuintro.tex       |  3 ++-
>  defer/rcurelated.tex     |  2 +-
>  defer/rcuusage.tex       | 14 ++++++++------
>  defer/seqlock.tex        |  4 ++--
>  defer/whichtochoose.tex  |  4 ++--
>  7 files changed, 23 insertions(+), 20 deletions(-)
> 
> -- 
> 2.17.1
> 

RE: [PATCH 00/13] Minor fixes for defer/

[SeongJae Park]

On Thu, 24 Nov 2022 12:48:23 -0800 "Paul E. McKenney" <paulmck@kernel.org> wrote:

> On Thu, Nov 24, 2022 at 10:57:49AM -0800, SeongJae Park wrote:
> > From: SeongJae Park <sj38.park@gmail.com>
> >
> > This patchset contains minor fixes for defer/ that found during the
> > Korean translation[1] of it.
> >
> > [1] https://github.com/sjp38/perfbook-ko_KR
> 
> Good catches, thank you!!!  Queued and pushed.
> 
> And a happy Thanksgiving weekend to you, assuming that you are still
> in Seattle.  ;-)

Thank you, and yes, I'm still in Seattle.  I was able to finish defer/
translation today thanks to the holiday.  And thank you again for your
contributions to the world that you made this year!  Happy Thanksgiving! :D


Thanks,
SJ

[...]