Skip to contentSkip to conversation

Minor fixes for defer/

PATCH In review SeongJae Park 2 participants 16 messages Nov 24, 2022

lore
Share & tools
lore
#0 lore raw

cover Minor fixes for defer/

From: SeongJae Park <[email protected]>

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(-)
Signature · 1 line
2.17.1
#1 lore raw

PATCH 1/13 defer/rcuintro: Clearly point the QSBR described section

From: SeongJae Park <[email protected]>

'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.

---
 defer/rcuintro.tex | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)
defer/rcuintro.tex +2 -1
index 2f4e7ee3..7007058b 100644
@@ -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
Signature · 1 line
2.17.1
#2 lore raw

PATCH 2/13 defer/rcufundamental: Add non-breaking spaces

In reply to SeongJae Park

From: SeongJae Park <[email protected]>

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

---
 defer/rcufundamental.tex | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)
defer/rcufundamental.tex +3 -3
index 39b2f7ff..5e7d6675 100644
@@ -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
Signature · 1 line
2.17.1
#3 lore raw

PATCH 3/13 defer/rcuapi: Add missed unbreakable spaces

In reply to SeongJae Park

From: SeongJae Park <[email protected]>

Add missed unbreakable spaces in defer/rcuapi.tex.

---
 defer/rcuapi.tex | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)
defer/rcuapi.tex +3 -3
index 8ee54866..425c64ff 100644
@@ -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.
Signature · 1 line
2.17.1
#4 lore raw

PATCH 4/13 defer/rcuapi: Use \co{} for boolean return value

In reply to SeongJae Park

From: SeongJae Park <[email protected]>

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

---
 defer/rcuapi.tex | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
defer/rcuapi.tex +2 -2
index 425c64ff..9ac2d26c 100644
@@ -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
Signature · 1 line
2.17.1
#5 lore raw

PATCH 5/13 defer/seqlock: Use \co{} for boolean return value

In reply to SeongJae Park

From: SeongJae Park <[email protected]>

\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.

---
 defer/seqlock.tex | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
defer/seqlock.tex +2 -2
index da1d19ec..f435a1af 100644
@@ -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{%
Signature · 1 line
2.17.1
#6 lore raw

PATCH 6/13 defer/rcuusage: Call paragraphs paragraphs, not sections

In reply to SeongJae Park

From: SeongJae Park <[email protected]>

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

---
 defer/rcuusage.tex | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
defer/rcuusage.tex +2 -2
index 9da0e04c..8c45093f 100644
@@ -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.
 
 
Signature · 1 line
2.17.1
#7 lore raw

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

In reply to SeongJae Park

From: SeongJae Park <[email protected]>

'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.

---
 defer/rcuusage.tex | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)
defer/rcuusage.tex +3 -1
index 8c45093f..18abf340 100644
@@ -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
Signature · 1 line
2.17.1
#8 lore raw

PATCH 8/13 defer/rcuusage: Add a missed unbreakable space

In reply to SeongJae Park

From: SeongJae Park <[email protected]>

---
 defer/rcuusage.tex | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
defer/rcuusage.tex +1 -1
index 18abf340..ba13bd96 100644
@@ -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.
Signature · 1 line
2.17.1
#9 lore raw

PATCH 9/13 defer/rcuusage: Add missing '()' for 'rcu_dereference()'

In reply to SeongJae Park

From: SeongJae Park <[email protected]>

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

---
 defer/rcuusage.tex | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
defer/rcuusage.tex +1 -1
index ba13bd96..1dc4c2ca 100644
@@ -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
Signature · 1 line
2.17.1
#10 lore raw

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

In reply to SeongJae Park

From: SeongJae Park <[email protected]>

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

---
 defer/rcuusage.tex | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
defer/rcuusage.tex +1 -1
index 1dc4c2ca..372a508d 100644
@@ -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.
Signature · 1 line
2.17.1
#11 lore raw

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

In reply to SeongJae Park

From: SeongJae Park <[email protected]>

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

---
 defer/rcurelated.tex | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
defer/rcurelated.tex +1 -1
index 1ca25d9e..190c8456 100644
@@ -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
Signature · 1 line
2.17.1
#12 lore raw

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

In reply to SeongJae Park

From: SeongJae Park <[email protected]>

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

---
 defer/whichtochoose.tex | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
defer/whichtochoose.tex +1 -1
index 489299a7..846c1ea1 100644
@@ -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}.
Signature · 1 line
2.17.1
#13 lore raw

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

In reply to SeongJae Park

From: SeongJae Park <[email protected]>

---
 defer/whichtochoose.tex | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
defer/whichtochoose.tex +1 -1
index 846c1ea1..dad3217a 100644
@@ -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
Signature · 1 line
2.17.1
#14 lore raw
In reply to SeongJae Park
Quoted 6 lines · SeongJae Park

From: SeongJae Park <[email protected]>

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

Quoted 28 lines

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(-)
Signature · 1 line
2.17.1
#15 lore raw
Quoted 6 lines · On Thu, 24 Nov 2022 12:48:23 -0800 "Paul E. McKenney" <[email protected]>…
Quoted 5 lines · SeongJae Park

From: SeongJae Park <[email protected]>

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

Quoted 6 lines
Quoted 1 line

[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

[...]