Minor fixes for defer/
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
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
@@ -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
PATCH 2/13 defer/rcufundamental: Add non-breaking spaces
In reply to SeongJae ParkFrom: 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
@@ -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
PATCH 3/13 defer/rcuapi: Add missed unbreakable spaces
In reply to SeongJae ParkFrom: 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
@@ -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
PATCH 4/13 defer/rcuapi: Use \co{} for boolean return value
In reply to SeongJae ParkFrom: 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
@@ -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
PATCH 5/13 defer/seqlock: Use \co{} for boolean return value
In reply to SeongJae ParkFrom: 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
@@ -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
PATCH 6/13 defer/rcuusage: Call paragraphs paragraphs, not sections
In reply to SeongJae ParkFrom: 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
@@ -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
PATCH 7/13 defer/rcuusage: Provide the reference to synchronous RCU update-side primitives
In reply to SeongJae ParkFrom: 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
@@ -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
PATCH 8/13 defer/rcuusage: Add a missed unbreakable space
In reply to SeongJae ParkFrom: SeongJae Park <[email protected]>
--- defer/rcuusage.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
defer/rcuusage.tex +1 -1
@@ -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
PATCH 9/13 defer/rcuusage: Add missing '()' for 'rcu_dereference()'
In reply to SeongJae ParkFrom: 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
@@ -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
PATCH 10/13 defer/rcuusage: Fix wrong function name: s/timer_stop/nmi_stop/
In reply to SeongJae ParkFrom: 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
@@ -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
PATCH 11/13 defer/rcurelated: Remove unopen closing parentheses
In reply to SeongJae ParkFrom: 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
@@ -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
PATCH 12/13 defer/whichtochoose: Fix a wrongly positioned unbreakable space
In reply to SeongJae ParkFrom: 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
@@ -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
PATCH 13/13 defer/whichtochoose: Remove an unnecessary space.
In reply to SeongJae ParkFrom: SeongJae Park <[email protected]>
--- defer/whichtochoose.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
defer/whichtochoose.tex +1 -1
@@ -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
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.
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
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
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
[...]