[PATCH RESEND -perfbook 00/10] Index and acronym updates

[PATCH RESEND -perfbook 00/10] Index and acronym updates

[Akira Yokosawa]

Hi Paul,

This is another round of *never-ending* indexing updates.

Patches 1/10--3/10 add indexing tags to terms recently added in Glossary.
Patch 4/10 adds API indexing tags in rcuapi.
Patch 5/10 fixes a typo found while working on Patch 4/10.

Patch 6/10 adds indexing tags for userspace-RCU APIs in datastruct.
Those APIs are also used in code snippets of other chapters, but are
seldom mentioned from the text in later chapters/sections.

Patches 7/10 and 8/10 add API indexing tags in count and locking.
Patch 9/10 defines acronym of QSBR and adds tags for QSBR and EBR.

Patch 10/10 defines acronym of RAII and adds its tags.  The "WIP" in
the title indicates changes in the appearance of first-time form from
quoted string to emphasized modifier form.  Please keep it with the change
log amended if the new appearance looks good/acceptable to you.

        Thanks, Akira
--
Akira Yokosawa (10):
  index: Add tags for 'reference count'
  index: Add tags for 'existence guarantee'
  index: Add tags for 'type-safe memory'
  defer/rcuapi: Add index tags for RCU APIs
  defer/rcuapi: Fix typo 'get_nulls_values()'
  datastruct: Add index tags for userspace-RCU APIs
  count: Add index tags to APIs
  locking: Add index tags to APIs
  treewide: Add acronym tags for QSBR and EBR
  WIP locking: Add acronym tag for RAII

 SMPdesign/SMPdesign.tex       |   4 +-
 appendix/toyrcu/toyrcu.tex    |   3 +-
 count/count.tex               |  16 ++---
 datastruct/datastruct.tex     |  14 ++--
 defer/rcuapi.tex              | 120 +++++++++++++++++-----------------
 defer/rcuintro.tex            |   3 +-
 defer/rcurelated.tex          |   4 +-
 defer/rcuusage.tex            |  11 ++--
 defer/refcnt.tex              |   3 +-
 defer/whichtochoose.tex       |   9 ++-
 future/tm.tex                 |   3 +-
 glsdict.tex                   |   2 +
 locking/locking-existence.tex |   2 +-
 locking/locking.tex           |  20 +++---
 memorder/memorder.tex         |   2 +-
 together/applyrcu.tex         |   2 +-
 together/refcnt.tex           |   8 ++-
 toolsoftrade/toolsoftrade.tex |   4 +-
 18 files changed, 118 insertions(+), 112 deletions(-)


base-commit: 3cc2d7eede268930304b35fdce6121e18b2ceef6
-- 
2.17.1

[PATCH RESEND -perfbook 01/10] index: Add tags for 'reference count'

[Akira Yokosawa]

Subject: [PATCH -perfbook 01/10] index: Add tags for 'reference count'

"Reference count" covers "reference counter" and "reference counting"
as well.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
 appendix/toyrcu/toyrcu.tex    | 3 ++-
 count/count.tex               | 2 +-
 defer/rcuusage.tex            | 3 ++-
 defer/refcnt.tex              | 3 ++-
 defer/whichtochoose.tex       | 4 ++--
 future/tm.tex                 | 3 ++-
 together/applyrcu.tex         | 2 +-
 together/refcnt.tex           | 3 ++-
 toolsoftrade/toolsoftrade.tex | 4 ++--
 9 files changed, 16 insertions(+), 11 deletions(-)

diff --git a/appendix/toyrcu/toyrcu.tex b/appendix/toyrcu/toyrcu.tex
index 9c474a37..2dbffbfc 100644
--- a/appendix/toyrcu/toyrcu.tex
+++ b/appendix/toyrcu/toyrcu.tex
@@ -29,7 +29,8 @@ RCU implementation based on simple locking, while
 \crefthro{sec:app:toyrcu:Per-Thread Lock-Based RCU}
 {sec:app:toyrcu:RCU Based on Quiescent States}
 present a series of
-simple RCU implementations based on locking, reference counters,
+simple RCU implementations based on locking,
+\IXalt{reference counters}{reference count},
 and free-running counters.
 Finally, \cref{sec:app:toyrcu:Summary of Toy RCU Implementations}
 provides a summary and a list of desirable RCU properties.
diff --git a/count/count.tex b/count/count.tex
index c8aa959b..2870506b 100644
--- a/count/count.tex
+++ b/count/count.tex
@@ -114,7 +114,7 @@ counting.
 
 \EQuickQuiz{
 	{\bfseries Removable I/O device access-count problem.}
-	Suppose that you need to maintain a reference count on a
+	Suppose that you need to maintain a \IX{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.
 	As usual, the user indicates a desire to remove the device, and
diff --git a/defer/rcuusage.tex b/defer/rcuusage.tex
index 811dd32a..c663be0b 100644
--- a/defer/rcuusage.tex
+++ b/defer/rcuusage.tex
@@ -1729,7 +1729,8 @@ Again, part of the answer is performance, as shown in
 fig:defer:Performance of Preemptible RCU vs. Reference Counting},
 again showing data taken on a 448-CPU 2.1\,GHz Intel x86 system
 for non-preemptible and preemptible Linux-kernel RCU, respectively.
-Non-preemptible RCU's advantage over reference counting ranges from
+Non-preemptible RCU's advantage over
+\IXalt{reference counting}{reference count} ranges from
 more than an order of magnitude at one CPU up to about four orders of
 magnitude at 192~CPUs.
 Preemptible RCU's advantage ranges from about a factor of three at
diff --git a/defer/refcnt.tex b/defer/refcnt.tex
index 14e2def6..179c0521 100644
--- a/defer/refcnt.tex
+++ b/defer/refcnt.tex
@@ -7,7 +7,8 @@
 %
 \epigraph{I am never letting you go!}{Unknown}
 
-Reference counting tracks the number of references to a given object in
+\IXalt{Reference counting}{reference count}
+tracks the number of references to a given object in
 order to prevent that object from being prematurely freed.
 As such, it has a long and honorable history of use dating back to
 at least an early 1960s Weizenbaum
diff --git a/defer/whichtochoose.tex b/defer/whichtochoose.tex
index e3ce4540..4782c036 100644
--- a/defer/whichtochoose.tex
+++ b/defer/whichtochoose.tex
@@ -82,8 +82,8 @@ techniques from one another.
 
 The ``Readers'' row summarizes the results presented in
 \cref{fig:defer:Pre-BSD Routing Table Protected by RCU QSBR},
-which shows that all but reference counting are enjoy reasonably
-fast and scalable readers.
+which shows that all but \IXalt{reference counting}{reference count}
+are enjoy reasonably fast and scalable readers.
 
 The ``Number of Protected Objects'' row evaluates each technique's need
 for external storage with which to record reader protection.
diff --git a/future/tm.tex b/future/tm.tex
index 50e7d6dc..8ed44405 100644
--- a/future/tm.tex
+++ b/future/tm.tex
@@ -869,7 +869,8 @@ exclusive locking.
 
 This section focuses mainly on RCU\@.
 Similar issues and possible resolutions arise when combining TM with
-other deferred-reclamation mechanisms such as reference counters and
+other deferred-reclamation mechanisms such as
+\IXalt{reference counters}{reference count} and
 hazard pointers.
 In the text below, known differences are specifically called out.
 
diff --git a/together/applyrcu.tex b/together/applyrcu.tex
index b26c7b6e..e3a0d2fe 100644
--- a/together/applyrcu.tex
+++ b/together/applyrcu.tex
@@ -575,7 +575,7 @@ update rates.
 \subsection{Scalable Reference Count Two}
 \label{sec:together:Scalable Reference Count Two}
 
-Suppose a reference count is becoming a performance or scalability
+Suppose a \IX{reference count} is becoming a performance or scalability
 bottleneck.
 What can you do?
 
diff --git a/together/refcnt.tex b/together/refcnt.tex
index 958fa383..292bdbd1 100644
--- a/together/refcnt.tex
+++ b/together/refcnt.tex
@@ -13,7 +13,8 @@ Although reference counting is a conceptually simple technique,
 many devils hide in the details when it is applied to concurrent
 software.
 After all, if the object was not subject to premature disposal,
-there would be no need for the reference counter in the first place.
+there would be no need for the
+\IXalt{reference counter}{reference count} in the first place.
 But if the object can be disposed of, what prevents disposal during
 the reference-acquisition process itself?
 
diff --git a/toolsoftrade/toolsoftrade.tex b/toolsoftrade/toolsoftrade.tex
index a6606e24..d2117fde 100644
--- a/toolsoftrade/toolsoftrade.tex
+++ b/toolsoftrade/toolsoftrade.tex
@@ -2459,8 +2459,8 @@ An atomic add that returns the new value is provided by
 Both \apik{atomic_add_unless()} and \apik{atomic_inc_not_zero()} provide
 conditional atomic operations, where nothing happens unless the
 original value of the atomic variable is different than the value
-specified (these are very handy for managing reference counters, for
-example).
+specified (these are very handy for managing
+\IXalt{reference counters}{reference count}, for example).
 
 An atomic exchange operation is provided by \apik{atomic_xchg()}, and
 the celebrated \acrmf{cas} operation is provided by
-- 
2.17.1

[PATCH RESEND -perfbook 02/10] index: Add tags for 'existence guarantee'

[Akira Yokosawa]

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
 SMPdesign/SMPdesign.tex       | 4 ++--
 defer/rcuusage.tex            | 4 ++--
 defer/whichtochoose.tex       | 2 +-
 locking/locking-existence.tex | 2 +-
 together/refcnt.tex           | 2 +-
 5 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/SMPdesign/SMPdesign.tex b/SMPdesign/SMPdesign.tex
index b2ebabf5..8f4655bc 100644
--- a/SMPdesign/SMPdesign.tex
+++ b/SMPdesign/SMPdesign.tex
@@ -415,8 +415,8 @@ bucket from being freed during the time that its lock was being acquired.
 	What are some ways of preventing a structure from being freed while
 	its lock is being acquired?
 }\QuickQuizAnswer{
-	Here are a few possible solutions to this \emph{existence guarantee}
-	problem:
+	Here are a few possible solutions to this
+	\emph{\IX{existence guarantee}} problem:
 
 	\begin{enumerate}
 	\item	Provide a statically allocated lock that is held while
diff --git a/defer/rcuusage.tex b/defer/rcuusage.tex
index c663be0b..f69201bb 100644
--- a/defer/rcuusage.tex
+++ b/defer/rcuusage.tex
@@ -588,7 +588,7 @@ element being freed and reallocated as the same type of structure
 while they are referencing it, but must prohibit a change in type.
 This guarantee, called ``type-safe memory'' in
 academic literature~\cite{Cheriton96a},
-is weaker than the existence guarantees discussed
+is weaker than the \IXpl{existence guarantee} discussed
 in \cref{sec:defer:Existence Guarantee},
 and is therefore quite a bit harder to work with.
 Type-safe memory algorithms in the Linux kernel make use of slab caches,
@@ -702,7 +702,7 @@ top of the existence guarantees described in the next section.
 \label{sec:defer:Existence Guarantee}
 
 Gamsa et al.~\cite{Gamsa99}
-discuss existence guarantees and describe how a mechanism
+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
 \cref{sec:locking:Lock-Based Existence Guarantees}
diff --git a/defer/whichtochoose.tex b/defer/whichtochoose.tex
index 4782c036..e54ad1df 100644
--- a/defer/whichtochoose.tex
+++ b/defer/whichtochoose.tex
@@ -261,7 +261,7 @@ provides more-detailed rules of thumb that can help you choose among the
 four deferred-processing techniques presented in this chapter.
 
 As shown in the ``Existence Guarantee'' row,
-if you need existence guarantees for linked
+if you need \IXpl{existence guarantee} for linked
 data elements, you must use reference counting, hazard pointers, or RCU\@.
 Sequence locks do not provide existence guarantees, instead providing
 detection of updates, retrying any read-side critical sections
diff --git a/locking/locking-existence.tex b/locking/locking-existence.tex
index 38e432a2..d0ee690c 100644
--- a/locking/locking-existence.tex
+++ b/locking/locking-existence.tex
@@ -8,7 +8,7 @@
 \epigraph{Existence precedes and rules essence.}{\emph{Jean-Paul Sartre}}
 
 A key challenge in parallel programming is to provide
-\emph{existence guarantees}~\cite{Gamsa99},
+\emph{\IXpl{existence guarantee}}~\cite{Gamsa99},
 so that attempts to access a given object can rely on that object
 being in existence throughout a given access attempt.
 
diff --git a/together/refcnt.tex b/together/refcnt.tex
index 292bdbd1..56c6baa9 100644
--- a/together/refcnt.tex
+++ b/together/refcnt.tex
@@ -31,7 +31,7 @@ use in concurrent software, including:
 	might seek help from another thread that already has a reference.
 \item	In some cases, hazard pointers may be used as a drop-in
 	replacement for reference counters.
-\item	An existence guarantee is provided for the object, thus preventing
+\item	An \IX{existence guarantee} is provided for the object, thus preventing
 	it from being freed while some other entity might be attempting
 	to acquire a reference.
 	Existence guarantees are often provided by automatic
-- 
2.17.1

[PATCH RESEND -perfbook 03/10] index: Add tags for 'type-safe memory'

[Akira Yokosawa]

"Type-safety guarantee" is indexed by this tag as well.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
 defer/rcuapi.tex    | 2 +-
 defer/rcuusage.tex  | 2 +-
 together/refcnt.tex | 3 ++-
 3 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/defer/rcuapi.tex b/defer/rcuapi.tex
index ee939341..c152251b 100644
--- a/defer/rcuapi.tex
+++ b/defer/rcuapi.tex
@@ -242,7 +242,7 @@ The \co{rcu_barrier()} primitive does this job.
 }
 
 Finally, RCU may be used to provide
-type-safe memory~\cite{Cheriton96a}, as described in
+\IX{type-safe memory}~\cite{Cheriton96a}, as described in
 \cref{sec:defer:Type-Safe Memory}.
 In the context of RCU, type-safe memory guarantees that a given
 data element will not change type during any RCU read-side critical section
diff --git a/defer/rcuusage.tex b/defer/rcuusage.tex
index f69201bb..a3a17f61 100644
--- a/defer/rcuusage.tex
+++ b/defer/rcuusage.tex
@@ -586,7 +586,7 @@ same type.
 In other words, these lockless algorithms can tolerate a given data
 element being freed and reallocated as the same type of structure
 while they are referencing it, but must prohibit a change in type.
-This guarantee, called ``type-safe memory'' in
+This guarantee, called ``\IX{type-safe memory}'' in
 academic literature~\cite{Cheriton96a},
 is weaker than the \IXpl{existence guarantee} discussed
 in \cref{sec:defer:Existence Guarantee},
diff --git a/together/refcnt.tex b/together/refcnt.tex
index 56c6baa9..1963ddd2 100644
--- a/together/refcnt.tex
+++ b/together/refcnt.tex
@@ -38,7 +38,8 @@ use in concurrent software, including:
 	garbage collectors, and, as is seen in
 	\cref{sec:defer:Hazard Pointers,sec:defer:Read-Copy Update (RCU)},
 	by hazard pointers and RCU, respectively.
-\item	A type-safety guarantee is provided for the object.
+\item	A \IXalt{type-safety guarantee}{type-safe memory}
+	is provided for the object.
 	An additional identity check must be performed once
 	the reference is acquired.
 	Type-safety guarantees can be provided by special-purpose
-- 
2.17.1

[PATCH RESEND -perfbook 04/10] defer/rcuapi: Add index tags for RCU APIs

[Akira Yokosawa]

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
 defer/rcuapi.tex | 116 +++++++++++++++++++++++------------------------
 1 file changed, 58 insertions(+), 58 deletions(-)

diff --git a/defer/rcuapi.tex b/defer/rcuapi.tex
index c152251b..6cd30c0f 100644
--- a/defer/rcuapi.tex
+++ b/defer/rcuapi.tex
@@ -181,20 +181,20 @@ The ``RCU'' column corresponds to the consolidation of the
 three Linux-kernel RCU
 implementations~\cite{PaulEMcKenney2019RCUCVE,McKenney:2019:CRS:3319647.3325836},
 in which RCU read-side critical sections start with
-\co{rcu_read_lock()}, \co{rcu_read_lock_bh()}, or \co{rcu_read_lock_sched()}
-and end with \co{rcu_read_unlock()}, \co{rcu_read_unlock_bh()},
-or \co{rcu_read_unlock_sched()}, respectively.
+\apik{rcu_read_lock()}, \apik{rcu_read_lock_bh()}, or \apik{rcu_read_lock_sched()}
+and end with \apik{rcu_read_unlock()}, \apik{rcu_read_unlock_bh()},
+or \apik{rcu_read_unlock_sched()}, respectively.
 Any region of code that disables bottom halves, interrupts, or preemption
 also acts as an RCU read-side critical section.
 RCU read-side critical sections may be nested.
 The corresponding synchronous update-side primitives,
-\co{synchronize_rcu()} and \co{synchronize_rcu_expedited()}, along with
-their synonym \co{synchronize_net()}, wait for any type of currently
+\apik{synchronize_rcu()} and \apik{synchronize_rcu_expedited()}, along with
+their synonym \apik{synchronize_net()}, wait for any type of currently
 executing RCU read-side critical sections to complete.
 The length of this wait is known as a ``\IX{grace period}'', and
-\co{synchronize_rcu_expedited()} is designed to reduce \IXh{grace-period}
+\apik{synchronize_rcu_expedited()} is designed to reduce \IXh{grace-period}
 {latency} at the expense of increased CPU overhead and IPIs.
-The asynchronous update-side primitive, \co{call_rcu()},
+The asynchronous update-side primitive, \apik{call_rcu()},
 invokes a specified function with a specified argument after a
 subsequent grace period.
 For example, \co{call_rcu(p,f);} will result in
@@ -204,7 +204,7 @@ There are situations,
 such as when unloading a Linux-kernel module that uses \co{call_rcu()},
 when it is necessary to wait for all
 outstanding RCU callbacks to complete~\cite{PaulEMcKenney2007rcubarrier}.
-The \co{rcu_barrier()} primitive does this job.
+The \apik{rcu_barrier()} primitive does this job.
 
 \QuickQuizSeries{%
 \QuickQuizB{
@@ -231,7 +231,7 @@ The \co{rcu_barrier()} primitive does this job.
 
 	But not in earlier kernels, and especially not when using
 	preemptible RCU\@!
-	You instead want \co{synchronize_irq()}.
+	You instead want \apik{synchronize_irq()}.
 	Alternatively, you can place calls to \co{rcu_read_lock()}
 	and \co{rcu_read_unlock()} in the specific interrupt handlers that
 	you want \co{synchronize_rcu()} to wait for.
@@ -248,23 +248,23 @@ In the context of RCU, type-safe memory guarantees that a given
 data element will not change type during any RCU read-side critical section
 that accesses it.
 To make use of RCU-based type-safe memory, pass
-\co{SLAB_TYPESAFE_BY_RCU} to \co{kmem_cache_create()}.
+\apik{SLAB_TYPESAFE_BY_RCU} to \apik{kmem_cache_create()}.
 
 The ``SRCU'' column in
 \cref{tab:defer:RCU Wait-to-Finish APIs}
 displays a specialized RCU API that permits general sleeping in SRCU
 read-side critical
 sections~\cite{PaulEMcKenney2006c}
-delimited by \co{srcu_read_lock()} and \co{srcu_read_unlock()}.
-However, unlike RCU, SRCU's \co{srcu_read_lock()} returns a value that
-must be passed into the corresponding \co{srcu_read_unlock()}.
+delimited by \apik{srcu_read_lock()} and \apik{srcu_read_unlock()}.
+However, unlike RCU, SRCU's \apik{srcu_read_lock()} returns a value that
+must be passed into the corresponding \apik{srcu_read_unlock()}.
 This difference is due to the fact that the SRCU user allocates an
-\co{srcu_struct} for each distinct SRCU usage.
+\apik{srcu_struct} for each distinct SRCU usage.
 These distinct \co{srcu_struct} structures prevent SRCU read-side critical
-sections from blocking unrelated \co{synchronize_srcu()} and
-\co{synchronize_srcu_expedited()} invocations.
-Of course, use of either \co{synchronize_srcu()} or
-\co{synchronize_srcu_expedited()} within an SRCU read-side critical
+sections from blocking unrelated \apik{synchronize_srcu()} and
+\apik{synchronize_srcu_expedited()} invocations.
+Of course, use of either \apik{synchronize_srcu()} or
+\apik{synchronize_srcu_expedited()} within an SRCU read-side critical
 section can result in self-deadlock, so should be avoided.
 As with RCU, SRCU's \co{synchronize_srcu_expedited()} decreases
 grace-period latency compared to \co{synchronize_srcu()}, but at
@@ -301,7 +301,7 @@ srcu_read_unlock(&ssb, idx);
 }\QuickQuizEnd
 
 Similar to normal RCU, self-deadlock can be avoided using the
-asynchronous \co{call_srcu()} function.
+asynchronous \apik{call_srcu()} function.
 However, special care must be taken when using \co{call_srcu()} because
 a single task could register SRCU callbacks very quickly.
 Given that SRCU allows readers to block for arbitrary periods of
@@ -310,7 +310,7 @@ In contrast, given the synchronous \co{synchronize_srcu()}
 interface, a given task must finish waiting for a given grace period
 before it can start waiting for the next one.
 
-Also similar to RCU, there is an \co{srcu_barrier()} function that waits
+Also similar to RCU, there is an \apik{srcu_barrier()} function that waits
 for all prior \co{call_srcu()} callbacks to be invoked.
 
 In other words, SRCU compensates for its extremely weak
@@ -345,7 +345,7 @@ The key to answering this question is to note that trampoline code
 never contains code that either directly or indirectly does a
 voluntary context switch.
 This code might be preempted, but it will never directly or indirectly
-invoke \co{schedule()}.
+invoke \apik{schedule()}.
 This suggests a variant of RCU having voluntary context switches and
 idle execution as its only quiescent states.
 This variant is Tasks RCU\@.
@@ -353,10 +353,10 @@ This variant is Tasks RCU\@.
 Tasks RCU is unusual in having no read-side marking functions, which
 is good given that its main use case has nowhere to put such markings.
 Instead, calls to \co{schedule()} serve directly as quiescent states.
-Updates can use \co{synchronize_rcu_tasks()} to wait for all pre-existing
+Updates can use \apik{synchronize_rcu_tasks()} to wait for all pre-existing
 trampoline execution to complete, or they can use its asynchronous
-counterpart, \co{call_rcu_tasks()}.
-There is also an \co{rcu_barrier_tasks()} that waits for completion
+counterpart, \apik{call_rcu_tasks()}.
+There is also an \apik{rcu_barrier_tasks()} that waits for completion
 of callbacks corresponding to all prior invocations of \co{call_rcu_tasks()}.
 There is no \co{synchronize_rcu_tasks_expedited()} because there has
 not yet been a request for it, though implementing a useful variant of
@@ -473,10 +473,10 @@ APIs described in
 \cref{sec:defer:RCU has List-Processing APIs}.
 
 The first category publishes pointers to new data items.
-The \co{rcu_assign_pointer()} primitive ensures that any
+The \apik{rcu_assign_pointer()} primitive ensures that any
 prior initialization remains ordered before the assignment to the
 pointer on weakly ordered machines.
-The \co{rcu_replace_pointer()} primitive updates the pointer just like
+The \apik{rcu_replace_pointer()} primitive updates the pointer just like
 \co{rcu_assign_pointer()} does, but also returns the previous value,
 just like \co{rcu_dereference_protected()} (see below) would, including
 the lockdep expression.
@@ -543,19 +543,19 @@ rcu_read_unlock();
 }\QuickQuizEndE
 }
 
-The \co{rcu_pointer_handoff()} primitive simply returns its sole argument,
+The \apik{rcu_pointer_handoff()} primitive simply returns its sole argument,
 but is useful to tooling checking for pointers being leaked from
 RCU read-side critical sections.
 Use of \co{rcu_pointer_handoff()} indicates to such tooling that protection
 of the structure in question has been handed off from RCU to some other
 mechanism, such as locking or reference counting.
 
-The \co{RCU_INIT_POINTER()} macro can be used to initialize RCU-protected
+The \apik{RCU_INIT_POINTER()} macro can be used to initialize RCU-protected
 pointers that have not yet been exposed to readers, or alternatively,
 to set RCU-protected pointers to \co{NULL}.
 In these restricted cases, the memory-barrier instructions provided by
 \co{rcu_assign_pointer()} are not needed.
-Similarly, \co{RCU_POINTER_INITIALIZER()} provides a \GCC-style
+Similarly, \apik{RCU_POINTER_INITIALIZER()} provides a \GCC-style
 structure initializer to allow easy initialization of RCU-protected
 pointers in structures.
 
@@ -568,9 +568,9 @@ read-side critical section could result in the pointed-to object being
 freed at any time.
 However, if the pointer is merely to be tested and not dereferenced,
 the freeing of the pointed-to object is not necessarily a problem.
-In this case, \co{rcu_access_pointer()} may be used.
+In this case, \apik{rcu_access_pointer()} may be used.
 Normally, however, RCU read-side protection is required, and so the
-\co{rcu_dereference()} primitive uses the Linux kernel's \co{lockdep}
+\apik{rcu_dereference()} primitive uses the Linux kernel's \co{lockdep}
 facility~\cite{JonathanCorbet2006lockdep} to verify that this
 \co{rcu_dereference()} invocation is under the protection of
 \co{rcu_read_lock()}, \co{srcu_read_lock()}, or some other RCU read-side
@@ -581,21 +581,21 @@ used outside of an RCU read-side critical section.
 
 Another situation where protection is not required is when update-side code
 accesses the RCU-protected pointer while holding the update-side lock.
-The \co{rcu_dereference_protected()} API member is provided for this
+The \apik{rcu_dereference_protected()} API member is provided for this
 situation.
 Its first parameter is the RCU-protected pointer, and the second
 parameter takes a lockdep expression describing which locks must be
 held in order for the access to be safe.
 Code invoked both from readers and updaters can use
-\co{rcu_dereference_check()}, which also takes a lockdep expression, but
+\apik{rcu_dereference_check()}, which also takes a lockdep expression, but
 which may also be invoked from read-side code not holding the locks.
 In some cases, the lockdep expressions can be very complex, for example,
 when using fine-grained locking, any of a very large number of locks
 might be held, and it might be quite difficult to work out which applies.
-In these (hopefully rare) cases, \co{rcu_dereference_raw()} provides
+In these (hopefully rare) cases, \apik{rcu_dereference_raw()} provides
 protection but does not check for being invoked within a reader or with
 any particular lock being held.
-The \co{rcu_dereference_raw_notrace()} API member acts similarly, but
+The \apik{rcu_dereference_raw_notrace()} API member acts similarly, but
 cannot be traced, and may therefore be safely used by tracing code.
 
 Although pretty much any linked structure can be accessed by manipulating
@@ -678,9 +678,9 @@ 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 \co{is_a_nulls()} function (which returns true
+The reader can use the \apik{is_a_nulls()} function (which returns true
 if passed an \co{hlist_nulls} \co{NULL} pointer) to determine when
-it reaches the end of a list, and the \co{get_nulls_value()} function
+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
 the type of \co{NULL} pointer.
 When \co{get_nulls_values()} returns an unexpected value, the reader
@@ -835,7 +835,7 @@ directory of the Linux-kernel source tree and at
 Linux Weekly News~\cite{PaulEMcKenney2019RCUAPI}.
 
 However, the remainder of this section expands on the use of
-\co{list_replace_rcu()}, given that this API member gave RCU its name.
+\apik{list_replace_rcu()}, given that this API member gave RCU its name.
 This API member is used to carry out more complex updates in which an
 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
@@ -921,7 +921,7 @@ other, not a mixture of the two.
 
 After the \co{synchronize_rcu()} on \clnref{sync_rcu} returns,
 a grace period will have elapsed, and so all reads that started before the
-\co{list_replace_rcu()} will have completed.
+\apik{list_replace_rcu()} will have completed.
 In particular, any readers that might have been holding references
 to the \co{5,6,7} element are guaranteed to have exited
 their RCU read-side critical sections, and are thus prohibited from
@@ -932,7 +932,7 @@ to the old element, as indicated its green shading in the sixth row of
 As far as the readers are concerned, we are back to having a single version
 of the list, but with the new element in place of the old.
 
-After the \co{kfree()} on \clnref{kfree} completes, the list will
+After the \apik{kfree()} on \clnref{kfree} completes, the list will
 appear as shown on the final row of
 \cref{fig:defer:RCU Replacement in Linked List}.
 \end{fcvref}
@@ -1002,21 +1002,21 @@ parameters, and return values allows the Linux kernel's \co{sparse}
 tool to detect situtations where RCU-protected pointers are
 incorrectly accessed using plain C-language loads and stores.
 
-Debug-object support is automatic for any \co{rcu_head} structures
+Debug-object support is automatic for any \apik{rcu_head} structures
 that are part of a structure obtained from the Linux kernel's
 memory allocators, but those building their own special-purpose
-memory allocators can use \co{init_rcu_head()} and \co{destroy_rcu_head()}
+memory allocators can use \apik{init_rcu_head()} and \apik{destroy_rcu_head()}
 at allocation and free time, respectively.
 Those using \co{rcu_head} structures allocated on the function-call
-stack (it happens!\@) may use \co{init_rcu_head_on_stack()}
-before first use and \co{destroy_rcu_head_on_stack()} after last use,
+stack (it happens!\@) may use \apik{init_rcu_head_on_stack()}
+before first use and \apik{destroy_rcu_head_on_stack()} after last use,
 but before returning from the function.
 Debug-object support allows detection of bugs involving passing the
 same \co{rcu_head} structure to \co{call_rcu()} and friends in
 quick succession, which is the \co{call_rcu()} counterpart to the
 infamous double-free class of memory-allocation bugs.
 
-Stall-warning control is provided by \co{rcu_cpu_stall_reset()}, which
+Stall-warning control is provided by \apik{rcu_cpu_stall_reset()}, which
 allows the caller to suppress RCU CPU stall warnings for the remainder
 of the current grace period.
 RCU CPU stall warnings help pinpoint situations where an RCU read-side
@@ -1024,18 +1024,18 @@ critical section runs for an excessive length of time, and it is useful
 for things like kernel debuggers to be able to suppress them, for example,
 when encountering a breakpoint.
 
-Callback checking is provided by \co{rcu_head_init()} and
-\co{rcu_head_after_call_rcu()}.
+Callback checking is provided by \apik{rcu_head_init()} and
+\apik{rcu_head_after_call_rcu()}.
 The former is invoked on an \co{rcu_head} structure before it is passed
 to \co{call_rcu()}, and then \co{rcu_head_after_call_rcu()} will
 check to see if the callback has been invoked with the specified
 function.
 
 Support for lockdep~\cite{JonathanCorbet2006lockdep} includes
-\co{rcu_read_lock_held()},
-\co{rcu_read_lock_bh_held()},
-\co{rcu_read_lock_sched_held()}, and
-\co{srcu_read_lock_held()},
+\apik{rcu_read_lock_held()},
+\apik{rcu_read_lock_bh_held()},
+\apik{rcu_read_lock_sched_held()}, and
+\apik{srcu_read_lock_held()},
 each of which returns \co{true} if invoked within the corresponding
 type of RCU read-side critical section.
 
@@ -1049,18 +1049,18 @@ 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, \co{rcu_is_watching()} returns true if
+to become quite ornate, \apik{rcu_is_watching()} returns 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
 apply to SRCU\@.
 
-\co{RCU_LOCKDEP_WARN()} emits a warning if lockdep is enabled and if
+\apik{RCU_LOCKDEP_WARN()} emits a warning if lockdep is enabled and if
 its argument evaluates to \co{true}.
 For example, \co{RCU_LOCKDEP_WARN(!rcu_read_lock_held())} would emit a
 warning if invoked outside of an RCU read-side critical section.
 
-\co{RCU_NONIDLE()} may be used to force RCU to watch when executing
+\apik{RCU_NONIDLE()} may be used to force RCU to watch when executing
 the statement that is passed in as the sole argument.
 For example, \co{RCU_NONIDLE(WARN_ON(!rcu_is_watching()))}
 would never emit a warning.
@@ -1068,7 +1068,7 @@ However, changes in the 2020--2021 timeframe extend RCU's reach deeper
 into the idle loop, which should greatly reduce or even eliminate the
 need for \co{RCU_NONIDLE()}.
 
-Finally,  \co{rcu_sleep_check()} emits a warning if invoked within
+Finally,  \apik{rcu_sleep_check()} emits a warning if invoked within
 an RCU, RCU-bh, or RCU-sched read-side critical section.
 
 \subsubsection{Where Can RCU's APIs Be Used?}
@@ -1087,10 +1087,10 @@ The RCU read-side primitives may be used in any environment, including NMI,
 the RCU mutation and asynchronous grace-period primitives may be used in any
 environment other than NMI, and, finally, the RCU synchronous grace-period
 primitives may be used only in process context.
-The RCU list-traversal primitives include \co{list_for_each_entry_rcu()},
-\co{hlist_for_each_entry_rcu()}, etc.
+The RCU list-traversal primitives include \apik{list_for_each_entry_rcu()},
+\apik{hlist_for_each_entry_rcu()}, etc.
 Similarly, the RCU list-mutation primitives include
-\co{list_add_rcu()}, \co{hlist_del_rcu()}, etc.
+\apik{list_add_rcu()}, \apik{hlist_del_rcu()}, etc.
 
 Note that primitives from other families of RCU may be substituted,
 for example, \co{srcu_read_lock()} may be used in any context
-- 
2.17.1

[PATCH RESEND -perfbook 05/10] defer/rcuapi: Fix typo 'get_nulls_values()'

[Akira Yokosawa]

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
 defer/rcuapi.tex | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/defer/rcuapi.tex b/defer/rcuapi.tex
index 6cd30c0f..ecbd4863 100644
--- a/defer/rcuapi.tex
+++ b/defer/rcuapi.tex
@@ -683,7 +683,7 @@ 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
 the type of \co{NULL} pointer.
-When \co{get_nulls_values()} returns an unexpected value, the reader
+When \co{get_nulls_value()} returns an unexpected value, the reader
 can take corrective action, for example, restarting its traversal from
 the beginning.
 
-- 
2.17.1

[PATCH RESEND -perfbook 06/10] datastruct: Add index tags for userspace-RCU APIs

[Akira Yokosawa]

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
 datastruct/datastruct.tex | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/datastruct/datastruct.tex b/datastruct/datastruct.tex
index 7186b611..99da03bf 100644
--- a/datastruct/datastruct.tex
+++ b/datastruct/datastruct.tex
@@ -493,8 +493,8 @@ shows \co{hashtab_lookup()} for the RCU-protected per-bucket-locked
 hash table.
 This is identical to that in
 \cref{lst:datastruct:Hash-Table Lookup}
-except that \co{cds_list_for_each_entry()} is replaced
-by \co{cds_list_for_each_entry_rcu()}.
+except that \apiur{cds_list_for_each_entry()} is replaced
+by \apiur{cds_list_for_each_entry_rcu()}.
 Both of these primitives traverse the hash chain referenced
 by \co{htb->htb_head} but \co{cds_list_for_each_entry_rcu()} also
 correctly enforces memory ordering in case of concurrent insertion.
@@ -545,12 +545,12 @@ shows \co{hashtab_add()} and \co{hashtab_del()}, both of which
 are quite similar to their counterparts in the non-RCU hash table
 shown in
 \cref{lst:datastruct:Hash-Table Modification}.
-The \co{hashtab_add()} function uses \co{cds_list_add_rcu()} instead
-of \co{cds_list_add()} in order to ensure proper ordering when
+The \co{hashtab_add()} function uses \apiur{cds_list_add_rcu()} instead
+of \apiur{cds_list_add()} in order to ensure proper ordering when
 an element is added to the hash table at the same time that it is
 being looked up.
-The \co{hashtab_del()} function uses \co{cds_list_del_rcu()} instead
-of \co{cds_list_del_init()} to allow for the case where an element is
+The \co{hashtab_del()} function uses \apiur{cds_list_del_rcu()} instead
+of \apiur{cds_list_del_init()} to allow for the case where an element is
 looked up just before it is deleted.
 Unlike \co{cds_list_del_init()}, \co{cds_list_del_rcu()} leaves the
 forward pointer intact, so that \co{hashtab_lookup()} can traverse
-- 
2.17.1

[PATCH RESEND -perfbook 07/10] count: Add index tags to APIs

[Akira Yokosawa]

List of tagged APIs:
  o __get_thread_var(): perfbook's own
  o for_each_thread():  perfbook's own
  o per_thread():       perfbook's own
  o __thread:           GCC extension
  o atomic_t:           Linux kernel
  o atomic_cmpxchg()    Linux kernel
  o pthread_kill()      POSIX

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
 count/count.tex | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/count/count.tex b/count/count.tex
index 2870506b..d2b39904 100644
--- a/count/count.tex
+++ b/count/count.tex
@@ -510,7 +510,7 @@ type \co{unsigned long} named, creatively enough, \co{counter}.
 
 \Clnrefrange{inc:b}{inc:e}
 show a function that increments the counters, using the
-\co{__get_thread_var()} primitive to locate the currently running
+\apipf{__get_thread_var()} primitive to locate the currently running
 thread's element of the \co{counter} array.
 Because this element is modified only by the corresponding thread,
 non-atomic increment suffices.
@@ -538,8 +538,8 @@ The use of \co{WRITE_ONCE()} prevents this optimization and others besides.
 
 \Clnrefrange{read:b}{read:e}
 show a function that reads out the aggregate value of the counter,
-using the \co{for_each_thread()} primitive to iterate over the list of
-currently running threads, and using the \co{per_thread()} primitive
+using the \apipf{for_each_thread()} primitive to iterate over the list of
+currently running threads, and using the \apipf{per_thread()} primitive
 to fetch the specified thread's counter.
 This code also uses \co{READ_ONCE()} to ensure that the compiler doesn't
 optimize these loads into oblivion.
@@ -721,7 +721,7 @@ This is the topic of the next section.
 \subsection{Per-Thread-Variable-Based Implementation}
 \label{sec:count:Per-Thread-Variable-Based Implementation}
 
-\GCC\ provides an \co{__thread} storage class that provides
+\GCC\ provides an \apig{__thread} storage class that provides
 per-thread storage.
 This can be used as shown in
 \cref{lst:count:Per-Thread Statistical Counters} (\path{count_end.c})
@@ -1914,7 +1914,7 @@ The \co{counter} and \co{countermax} variables in earlier algorithms
 are combined into the single variable \co{counterandmax} shown on
 \clnref{candmax}, with \co{counter} in the upper half and \co{countermax} in
 the lower half.
-This variable is of type \co{atomic_t}, which has an underlying
+This variable is of type \apik{atomic_t}, which has an underlying
 representation of \co{int}.
 
 \Clnrefrange{def:b}{def:e} show the definitions for \co{globalcountmax}, \co{globalcount},
@@ -2007,7 +2007,7 @@ shows the \co{add_count()} and \co{sub_count()} functions.
 with the remainder of the function being the slowpath.
 \Clnrefrange{fast:b}{loop:e} of the fastpath form a compare-and-swap
 (CAS) loop, with
-the \co{atomic_cmpxchg()} primitive on
+the \apik{atomic_cmpxchg()} primitive on
 \clnrefrange{atmcmpex}{loop:e} performing the
 actual CAS\@.
 \Clnref{split} splits the current thread's \co{counterandmax} variable into its
@@ -2625,7 +2625,7 @@ left as an exercise for the reader, as is the analysis of
 \cref{lst:count:Signal-Theft Limit Counter Initialization Functions}
 show \co{count_init()}, which set up \co{flush_local_count_sig()}
 as the signal handler for \co{SIGUSR1},
-enabling the \co{pthread_kill()} calls in \co{flush_local_count()}
+enabling the \apipx{pthread_kill()} calls in \co{flush_local_count()}
 to invoke \co{flush_local_count_sig()}.
 The code for thread registry and unregistry is similar to that of
 earlier examples, so its analysis is left as an exercise for the
-- 
2.17.1

[PATCH RESEND -perfbook 08/10] locking: Add index tags to APIs

[Akira Yokosawa]

List of tagged APIs

  o call_rcu():            Linux kernel
  o pthread_cond_wait()    POSIX
  o pthread_mutex_t        POSIX
  o spin_trylock()         Linux kernel
  o pthread_mutex_lock()   POSIX
  o fork()                 POSIX
  o exec()                 POSIX
  o pthread_atfork()       POSIX

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
 locking/locking.tex | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/locking/locking.tex b/locking/locking.tex
index 18d52e36..2a6068a7 100644
--- a/locking/locking.tex
+++ b/locking/locking.tex
@@ -461,7 +461,7 @@ Some alternatives to highly layered locking hierarchies are covered in
 
 One way to avoid deadlock is to defer acquisition of one of the
 conflicting locks.
-This approach is used in Linux-kernel RCU, whose \co{call_rcu()}
+This approach is used in Linux-kernel RCU, whose \apik{call_rcu()}
 function is invoked by the Linux-kernel scheduler while holding
 its locks.
 This means that \co{call_rcu()} cannot always safely invoke the scheduler
@@ -516,8 +516,8 @@ principle.
 One exception is functions that hand off some entity,
 where the caller's lock must be held until the handoff is complete,
 but where the lock must be released before the function returns.
-One example of such a function is the POSIX \co{pthread_cond_wait()}
-function, where passing an pointer to a \co{pthread_mutex_t}
+One example of such a function is the POSIX \apipx{pthread_cond_wait()}
+function, where passing an pointer to a \apipx{pthread_mutex_t}
 prevents hangs due to lost wakeups.
 
 \QuickQuiz{
@@ -583,7 +583,7 @@ conditionally, as shown in
 \cref{lst:locking:Avoiding Deadlock Via Conditional Locking}.
 \begin{fcvref}[ln:locking:Avoiding Deadlock Via Conditional Locking]
 Instead of unconditionally acquiring the layer-1 lock, \clnref{trylock}
-conditionally acquires the lock using the \co{spin_trylock()} primitive.
+conditionally acquires the lock using the \apik{spin_trylock()} primitive.
 This primitive acquires the lock immediately if the lock is available
 (returning non-zero), and otherwise returns zero without acquiring the lock.
 
@@ -730,7 +730,7 @@ and several others are presented in
 \label{sec:locking:Signal/Interrupt Handlers}
 
 Deadlocks involving signal handlers are often quickly dismissed by
-noting that it is not legal to invoke \co{pthread_mutex_lock()} from
+noting that it is not legal to invoke \apipx{pthread_mutex_lock()} from
 within a signal handler~\cite{OpenGroup1997pthreads}.
 However, it is possible (though often unwise) to hand-craft
 locking primitives that \emph{can} be invoked from signal handlers.
@@ -2350,7 +2350,7 @@ human intuition~\cite{StevenRostedt2011locdepCryptic}.
 \label{sec:locking:Library Functions Used Between fork() and exec()}
 
 As noted earlier, if a thread executing a library function is holding
-a lock at the time that some other thread invokes \co{fork()}, the
+a lock at the time that some other thread invokes \apipx{fork()}, the
 fact that the parent's memory is copied to create the child means that
 this lock will be born held in the child's context.
 The thread that will release this lock is running in the parent, but not
@@ -2364,7 +2364,7 @@ to \co{fork()} a child process while the process is still single-threaded,
 and have this child process remain single-threaded.
 Requests to create further child processes can then be communicated
 to this initial child process, which can safely carry out any
-needed \co{fork()} and \co{exec()} system calls on behalf of its
+needed \co{fork()} and \apipx{exec()} system calls on behalf of its
 multi-threaded parent process.
 
 Another rather less pragmatic and straightforward solution to this problem
@@ -2383,7 +2383,7 @@ However, this approach has a couple of vulnerabilities:
 	This could again result in arbitrary memory corruption.
 \end{enumerate}
 
-The \co{pthread_atfork()} function is provided to help deal with these situations.
+The \apipx{pthread_atfork()} function is provided to help deal with these situations.
 The idea is to register a triplet of functions, one to be called by the
 parent before the \co{fork()}, one to be called by the parent after the
 \co{fork()}, and one to be called by the child after the \co{fork()}.
-- 
2.17.1

[PATCH RESEND -perfbook 09/10] treewide: Add acronym tags for QSBR and EBR

[Akira Yokosawa]

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
 datastruct/datastruct.tex | 2 +-
 defer/rcuintro.tex        | 3 +--
 defer/rcurelated.tex      | 4 ++--
 defer/rcuusage.tex        | 2 +-
 defer/whichtochoose.tex   | 3 +--
 memorder/memorder.tex     | 2 +-
 6 files changed, 7 insertions(+), 9 deletions(-)

diff --git a/datastruct/datastruct.tex b/datastruct/datastruct.tex
index 99da03bf..27f6b9a3 100644
--- a/datastruct/datastruct.tex
+++ b/datastruct/datastruct.tex
@@ -694,7 +694,7 @@ 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.
 \Cref{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
+therefore adds the results for the \IXacr{qsbr} variant of RCU, whose read-side
 primitives do nothing.
 And although QSBR does perform slightly better than does RCU, it is still
 about a factor of five short of ideal.
diff --git a/defer/rcuintro.tex b/defer/rcuintro.tex
index d87c18c1..b03eef26 100644
--- a/defer/rcuintro.tex
+++ b/defer/rcuintro.tex
@@ -328,8 +328,7 @@ state shown at the bottom of
 \label{fig:defer:QSBR: Waiting for Pre-Existing Readers}
 \end{figure}
 
-This approach is termed \emph{quiescent state based reclamation}
-(QSBR)~\cite{ThomasEHart2006a}.
+This approach is termed \IXacrfst{qsbr}~\cite{ThomasEHart2006a}.
 A QSBR schematic is shown in
 \cref{fig:defer:QSBR: Waiting for Pre-Existing Readers},
 with time advancing from the top of the figure to the bottom.
diff --git a/defer/rcurelated.tex b/defer/rcurelated.tex
index 48622df8..57b2679d 100644
--- a/defer/rcurelated.tex
+++ b/defer/rcurelated.tex
@@ -267,8 +267,8 @@ other aspects of concurrency.
 \ppl{Joseph}{Tassarotti} (Carnegie-Mellon University), \ppl{Derek}{Dreyer} (Max
 Planck Institute for Software Systems), and \ppl{Viktor}{Vafeiadis}
 (also MPI-SWS)~\cite{JosephTassarotti2015RCUproof}
-produced a manual formal proof of correctness of the quiescent-state-based
-reclamation (QSBR) variant of userspace
+produced a manual formal proof of correctness of the \IXacrf{qsbr}
+variant of userspace
 RCU~\cite{MathieuDesnoyers2009URCU,MathieuDesnoyers2012URCU}.
 \ppl{Lihao}{Liang} (University of Oxford), \pplmdl{Paul E.}{McKenney} (IBM),
 \ppl{Daniel}{Kroening}, and \ppl{Tom}{Melham}
diff --git a/defer/rcuusage.tex b/defer/rcuusage.tex
index a3a17f61..5f1e2aa2 100644
--- a/defer/rcuusage.tex
+++ b/defer/rcuusage.tex
@@ -110,7 +110,7 @@ flavor of userspace
 RCU~\cite{MathieuDesnoyers2009URCU,PaulMcKenney2013LWNURCU},
 for which \co{rcu_read_lock()} and \co{rcu_read_unlock()}
 generate a small amount of code.
-What happens for the QSBR flavor of RCU, which generates no code at all
+What happens for the \IXacr{qsbr} flavor of RCU, which generates no code at all
 for \co{rcu_read_lock()} and \co{rcu_read_unlock()}?
 (See \cref{sec:defer:Introduction to RCU},
 and especially
diff --git a/defer/whichtochoose.tex b/defer/whichtochoose.tex
index e54ad1df..4fec94df 100644
--- a/defer/whichtochoose.tex
+++ b/defer/whichtochoose.tex
@@ -524,8 +524,7 @@ In 2015, Maxim Khizhinsky added RCU to
 libcds~\cite{MaxKhiszinsky2015C++RCU}.
 
 Mindaugas Rasiukevicius implemented libqsbr in 2016, which features
-QSBR and epoch-based reclamation
-(EBR)~\cite{MindaugasRasiukevicius2016libqsbr},
+\IXacr{qsbr} and \IXacrf{ebr}~\cite{MindaugasRasiukevicius2016libqsbr},
 both of which are types of implementations of RCU\@.
 
 Sheth et al.~\cite{HarshalSheth2016goRCU}
diff --git a/memorder/memorder.tex b/memorder/memorder.tex
index cd828b0a..0305a71a 100644
--- a/memorder/memorder.tex
+++ b/memorder/memorder.tex
@@ -3683,7 +3683,7 @@ This litmus test's cycle is also allowed.
 
 Of course, lack of ordering in both these litmus tests should be absolutely
 no surprise, given that both \co{rcu_read_lock()} and \co{rcu_read_unlock()}
-are no-ops in the QSBR implementation of RCU\@.
+are no-ops in the \IXacr{qsbr} implementation of RCU\@.
 
 \subsubsection{RCU Update-Side Ordering}
 \label{sec:memorder:RCU Update-Side Ordering}
-- 
2.17.1

[PATCH RESEND -perfbook 10/10] WIP locking: Add acronym tag for RAII

[Akira Yokosawa]

The use of \IXacrmfst{} macro changes the resulting sentence from:

  ... to use the object-oriented "resource allocation is
  initialization" (RAII) pattern [...].

to:

  ... to use the object-oriented \emph{resource-allocation-is-
  initialization} (RAII} pattern [...].

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
 glsdict.tex         | 2 ++
 locking/locking.tex | 4 ++--
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/glsdict.tex b/glsdict.tex
index c861e09b..7f7ae336 100644
--- a/glsdict.tex
+++ b/glsdict.tex
@@ -229,6 +229,8 @@
 \newacronym{numa}{NUMA}{non-uniform memory architecture}
 \newacronym{qsbr}{QSBR}{quiescent-state-based reclamation}
 \newabbreviation{qsbr:m}{QSBR}{quiescent-state-based-reclamation}
+\newacronym{raii}{RAII}{resource allocation is initialization}
+\newabbreviation{raii:m}{RAII}{resource-allocation-is-initialization}
 \newacronym{rcu}{RCU}{read-copy update}
 \newacronym{smp}{SMP}{symmetric multiprocessing}
 \newabbreviation{smp:m}{SMP}{symmetric-multiprocessing}
diff --git a/locking/locking.tex b/locking/locking.tex
index 2a6068a7..851a1f00 100644
--- a/locking/locking.tex
+++ b/locking/locking.tex
@@ -1571,8 +1571,8 @@ compared to VAX/VMS's six.
 The locking primitives discussed thus far require explicit acquisition and
 release primitives, for example, \co{spin_lock()} and \co{spin_unlock()},
 respectively.
-Another approach is to use the object-oriented ``resource allocation
-is initialization'' (RAII) pattern~\cite{MargaretAEllis1990Cplusplus}.\footnote{
+Another approach is to use the object-oriented \IXacrmfst{raii}
+pattern~\cite{MargaretAEllis1990Cplusplus}.\footnote{
 	Though more clearly expressed at
 	\url{https://www.stroustrup.com/bs_faq2.html\#finally}.}
 This pattern is often applied to auto variables in languages like C++,
-- 
2.17.1

Re: [PATCH RESEND -perfbook 00/10] Index and acronym updates

[Paul E. McKenney]

On Thu, Jan 06, 2022 at 04:29:25PM +0900, Akira Yokosawa wrote:
> Hi Paul,
> 
> This is another round of *never-ending* indexing updates.

Maintaining indexes is non-trivial, no two ways about it!

So special thanks for this series!

At some point, for the index entries with lots of references, it may
be necesary to flag the most important references.  I sometimes see
such entries italicized or marked with "ff", though I freely confess
that I have no idea what the rationale for "ff" might be.

We are probably not yet to the point where this matters, though.

> Patches 1/10--3/10 add indexing tags to terms recently added in Glossary.
> Patch 4/10 adds API indexing tags in rcuapi.
> Patch 5/10 fixes a typo found while working on Patch 4/10.
> 
> Patch 6/10 adds indexing tags for userspace-RCU APIs in datastruct.
> Those APIs are also used in code snippets of other chapters, but are
> seldom mentioned from the text in later chapters/sections.
> 
> Patches 7/10 and 8/10 add API indexing tags in count and locking.
> Patch 9/10 defines acronym of QSBR and adds tags for QSBR and EBR.
> 
> Patch 10/10 defines acronym of RAII and adds its tags.  The "WIP" in
> the title indicates changes in the appearance of first-time form from
> quoted string to emphasized modifier form.  Please keep it with the change
> log amended if the new appearance looks good/acceptable to you.

I kept 10/10, removing the "WIP" on the second try.  ;-)

Queued and pushed, and again, thank you!

							Thanx, Paul

>         Thanks, Akira
> --
> Akira Yokosawa (10):
>   index: Add tags for 'reference count'
>   index: Add tags for 'existence guarantee'
>   index: Add tags for 'type-safe memory'
>   defer/rcuapi: Add index tags for RCU APIs
>   defer/rcuapi: Fix typo 'get_nulls_values()'
>   datastruct: Add index tags for userspace-RCU APIs
>   count: Add index tags to APIs
>   locking: Add index tags to APIs
>   treewide: Add acronym tags for QSBR and EBR
>   WIP locking: Add acronym tag for RAII
> 
>  SMPdesign/SMPdesign.tex       |   4 +-
>  appendix/toyrcu/toyrcu.tex    |   3 +-
>  count/count.tex               |  16 ++---
>  datastruct/datastruct.tex     |  14 ++--
>  defer/rcuapi.tex              | 120 +++++++++++++++++-----------------
>  defer/rcuintro.tex            |   3 +-
>  defer/rcurelated.tex          |   4 +-
>  defer/rcuusage.tex            |  11 ++--
>  defer/refcnt.tex              |   3 +-
>  defer/whichtochoose.tex       |   9 ++-
>  future/tm.tex                 |   3 +-
>  glsdict.tex                   |   2 +
>  locking/locking-existence.tex |   2 +-
>  locking/locking.tex           |  20 +++---
>  memorder/memorder.tex         |   2 +-
>  together/applyrcu.tex         |   2 +-
>  together/refcnt.tex           |   8 ++-
>  toolsoftrade/toolsoftrade.tex |   4 +-
>  18 files changed, 118 insertions(+), 112 deletions(-)
> 
> 
> base-commit: 3cc2d7eede268930304b35fdce6121e18b2ceef6
> -- 
> 2.17.1
> 

Re: [PATCH RESEND -perfbook 00/10] Index and acronym updates

[Paul E. McKenney]

On Thu, Jan 06, 2022 at 08:19:45AM -0800, Paul E. McKenney wrote:
> On Thu, Jan 06, 2022 at 04:29:25PM +0900, Akira Yokosawa wrote:
> > Hi Paul,
> > 
> > This is another round of *never-ending* indexing updates.
> 
> Maintaining indexes is non-trivial, no two ways about it!
> 
> So special thanks for this series!
> 
> At some point, for the index entries with lots of references, it may
> be necesary to flag the most important references.  I sometimes see
> such entries italicized or marked with "ff", though I freely confess
> that I have no idea what the rationale for "ff" might be.

And I did find this.  The "ff" stands for "folios following", where
"folio" is used in the sense of "page".  So "368 ff" means "page 368
and some number of subsequent pages."

I have spent most of my life fooled into thinking that "ff" indicated
the most significant page for a given index item.  But there is some
connection, at least assuming that a longer discussion of a given term
is a more significant discussion of that term.  ;-)

							Thanx, Paul

Re: [PATCH RESEND -perfbook 00/10] Index and acronym updates

[Akira Yokosawa]

On Fri, 7 Jan 2022 21:07:04 -0800,
Paul E. McKenney wrote:
> On Thu, Jan 06, 2022 at 08:19:45AM -0800, Paul E. McKenney wrote:
>> On Thu, Jan 06, 2022 at 04:29:25PM +0900, Akira Yokosawa wrote:
>>> Hi Paul,
>>>
>>> This is another round of *never-ending* indexing updates.
>>
>> Maintaining indexes is non-trivial, no two ways about it!
>>
>> So special thanks for this series!
>>
>> At some point, for the index entries with lots of references, it may
>> be necesary to flag the most important references.  I sometimes see
>> such entries italicized or marked with "ff", though I freely confess
>> that I have no idea what the rationale for "ff" might be.
> 
> And I did find this.  The "ff" stands for "folios following", where
> "folio" is used in the sense of "page".  So "368 ff" means "page 368
> and some number of subsequent pages."
> 
> I have spent most of my life fooled into thinking that "ff" indicated
> the most significant page for a given index item.  But there is some
> connection, at least assuming that a longer discussion of a given term
> is a more significant discussion of that term.  ;-)

So, prompted by your comment, I'm experimenting change of page number
styles referenced in index.

You can see a WIP tree at:

--------
The following changes since commit 6eca56ccde0839f4ea81c5f02ddbe4c7c97e225f:

  Fix a typo in Bibliography (2022-01-12 09:48:13 -0800)

are available in the Git repository at:

  https://github.com/akiyks/perfbook.git tags/WIP-index-page-style-2022.01.14

for you to fetch changes up to cc9e388aee6cd72ed757fa0ec193b8e35f2bbaff:

  index: Retouch prenote layout (2022-01-14 17:41:30 +0900)

----------------------------------------------------------------
Akira Yokosawa (6):
      Initial indexformat support
      locking, defer: POC of bold face page number in index
      defer: POC of hierarchical index with modifier part's case preserved
      index: Add prenotes of legends in Index pages
      index, glossary: Add underline for pages in Glossary
      index: Retouch prenote layout

 defer/rcu.tex                  |   2 +-
 defer/rcufundamental.tex       |   2 +-
 defer/rcuintro.tex             |   2 +-
 glossary.tex                   | 176 ++++++++++++++++++++---------------------
 glsdict.tex                    |  10 ++-
 locking/locking.tex            |   4 +-
 perfbook-lt.tex                |  67 +++++++++++++++-
 utilities/adjustindexformat.pl |  20 +++++
 utilities/runlatex.sh          |   2 +
 9 files changed, 189 insertions(+), 96 deletions(-)
 create mode 100755 utilities/adjustindexformat.pl
--------

This is not yet ready for pull.  I need to expand change logs
at least.

If we were using plain \index{} macro for tagging terms, you could
say:

    \index{some word|textit}

to italicize its page number.
However, \IX{some word|textit} does not work.

So I need to define a number of macros:

  \IXB{}, \IXBh{}{}, ... -> Bold, for that "ff" case
  \IXG{}, \IXGh{}{}. ... -> Underline, for definitions in Glossary

, and to use one of them where you want to emphasize.

The "B" in \IXB came from "Bold", but actual style of emphasis can
be changed easily by redefining the \BF{} command.
\IXF{} might be a better name.  (Macro names embedded in .tex
files need to be stable.)

Furthermore, I have not figured out the way to make those
macros generate proper-format index entries in .idx file.
This is mostly because I'm not good at low-level TeX programming.

So I added adjustindexformat.pl so that it can be amended before
fed into "makeindex".

I'd like you to have a look at the changes and resulting looks of
Index pages.

Any feedback is welcome!

        Thanks, Akira

> 
> 							Thanx, Paul
> 

Re: [PATCH RESEND -perfbook 00/10] Index and acronym updates

[Paul E. McKenney]

On Fri, Jan 14, 2022 at 07:11:51PM +0900, Akira Yokosawa wrote:
> On Fri, 7 Jan 2022 21:07:04 -0800,
> Paul E. McKenney wrote:
> > On Thu, Jan 06, 2022 at 08:19:45AM -0800, Paul E. McKenney wrote:
> >> On Thu, Jan 06, 2022 at 04:29:25PM +0900, Akira Yokosawa wrote:
> >>> Hi Paul,
> >>>
> >>> This is another round of *never-ending* indexing updates.
> >>
> >> Maintaining indexes is non-trivial, no two ways about it!
> >>
> >> So special thanks for this series!
> >>
> >> At some point, for the index entries with lots of references, it may
> >> be necesary to flag the most important references.  I sometimes see
> >> such entries italicized or marked with "ff", though I freely confess
> >> that I have no idea what the rationale for "ff" might be.
> > 
> > And I did find this.  The "ff" stands for "folios following", where
> > "folio" is used in the sense of "page".  So "368 ff" means "page 368
> > and some number of subsequent pages."
> > 
> > I have spent most of my life fooled into thinking that "ff" indicated
> > the most significant page for a given index item.  But there is some
> > connection, at least assuming that a longer discussion of a given term
> > is a more significant discussion of that term.  ;-)
> 
> So, prompted by your comment, I'm experimenting change of page number
> styles referenced in index.
> 
> You can see a WIP tree at:
> 
> --------
> The following changes since commit 6eca56ccde0839f4ea81c5f02ddbe4c7c97e225f:
> 
>   Fix a typo in Bibliography (2022-01-12 09:48:13 -0800)
> 
> are available in the Git repository at:
> 
>   https://github.com/akiyks/perfbook.git tags/WIP-index-page-style-2022.01.14
> 
> for you to fetch changes up to cc9e388aee6cd72ed757fa0ec193b8e35f2bbaff:
> 
>   index: Retouch prenote layout (2022-01-14 17:41:30 +0900)
> 
> ----------------------------------------------------------------
> Akira Yokosawa (6):
>       Initial indexformat support
>       locking, defer: POC of bold face page number in index
>       defer: POC of hierarchical index with modifier part's case preserved
>       index: Add prenotes of legends in Index pages
>       index, glossary: Add underline for pages in Glossary
>       index: Retouch prenote layout
> 
>  defer/rcu.tex                  |   2 +-
>  defer/rcufundamental.tex       |   2 +-
>  defer/rcuintro.tex             |   2 +-
>  glossary.tex                   | 176 ++++++++++++++++++++---------------------
>  glsdict.tex                    |  10 ++-
>  locking/locking.tex            |   4 +-
>  perfbook-lt.tex                |  67 +++++++++++++++-
>  utilities/adjustindexformat.pl |  20 +++++
>  utilities/runlatex.sh          |   2 +
>  9 files changed, 189 insertions(+), 96 deletions(-)
>  create mode 100755 utilities/adjustindexformat.pl
> --------
> 
> This is not yet ready for pull.  I need to expand change logs
> at least.
> 
> If we were using plain \index{} macro for tagging terms, you could
> say:
> 
>     \index{some word|textit}
> 
> to italicize its page number.
> However, \IX{some word|textit} does not work.
> 
> So I need to define a number of macros:
> 
>   \IXB{}, \IXBh{}{}, ... -> Bold, for that "ff" case
>   \IXG{}, \IXGh{}{}. ... -> Underline, for definitions in Glossary
> 
> , and to use one of them where you want to emphasize.
> 
> The "B" in \IXB came from "Bold", but actual style of emphasis can
> be changed easily by redefining the \BF{} command.
> \IXF{} might be a better name.  (Macro names embedded in .tex
> files need to be stable.)

I will play with this later today, Pacific Time, but in the meantime I
just wanted to say that having the most significant page number in an
index list be bold works just fine.  If we have bold, there is no need
for italics!

							Thanx, Paul

> Furthermore, I have not figured out the way to make those
> macros generate proper-format index entries in .idx file.
> This is mostly because I'm not good at low-level TeX programming.
> 
> So I added adjustindexformat.pl so that it can be amended before
> fed into "makeindex".
> 
> I'd like you to have a look at the changes and resulting looks of
> Index pages.
> 
> Any feedback is welcome!
> 
>         Thanks, Akira
> 
> > 
> > 							Thanx, Paul
> > 

Re: [PATCH RESEND -perfbook 00/10] Index and acronym updates

[Akira Yokosawa]

On Fri, 14 Jan 2022 05:47:28 -0800,
Paul E. McKenney wrote:
> On Fri, Jan 14, 2022 at 07:11:51PM +0900, Akira Yokosawa wrote:
>> On Fri, 7 Jan 2022 21:07:04 -0800,
>> Paul E. McKenney wrote:
>>> On Thu, Jan 06, 2022 at 08:19:45AM -0800, Paul E. McKenney wrote:
>>>> On Thu, Jan 06, 2022 at 04:29:25PM +0900, Akira Yokosawa wrote:
>>>>> Hi Paul,
>>>>>
>>>>> This is another round of *never-ending* indexing updates.
>>>>
>>>> Maintaining indexes is non-trivial, no two ways about it!
>>>>
>>>> So special thanks for this series!
>>>>
>>>> At some point, for the index entries with lots of references, it may
>>>> be necesary to flag the most important references.  I sometimes see
>>>> such entries italicized or marked with "ff", though I freely confess
>>>> that I have no idea what the rationale for "ff" might be.
>>>
>>> And I did find this.  The "ff" stands for "folios following", where
>>> "folio" is used in the sense of "page".  So "368 ff" means "page 368
>>> and some number of subsequent pages."
>>>
>>> I have spent most of my life fooled into thinking that "ff" indicated
>>> the most significant page for a given index item.  But there is some
>>> connection, at least assuming that a longer discussion of a given term
>>> is a more significant discussion of that term.  ;-)
>>
>> So, prompted by your comment, I'm experimenting change of page number
>> styles referenced in index.
>>
>> You can see a WIP tree at:
>>
>> --------
>> The following changes since commit 6eca56ccde0839f4ea81c5f02ddbe4c7c97e225f:
>>
>>   Fix a typo in Bibliography (2022-01-12 09:48:13 -0800)
>>
>> are available in the Git repository at:
>>
>>   https://github.com/akiyks/perfbook.git tags/WIP-index-page-style-2022.01.14
>>
>> for you to fetch changes up to cc9e388aee6cd72ed757fa0ec193b8e35f2bbaff:
>>
>>   index: Retouch prenote layout (2022-01-14 17:41:30 +0900)
>>
>> ----------------------------------------------------------------
>> Akira Yokosawa (6):
>>       Initial indexformat support
>>       locking, defer: POC of bold face page number in index
>>       defer: POC of hierarchical index with modifier part's case preserved
>>       index: Add prenotes of legends in Index pages
>>       index, glossary: Add underline for pages in Glossary
>>       index: Retouch prenote layout
>>
>>  defer/rcu.tex                  |   2 +-
>>  defer/rcufundamental.tex       |   2 +-
>>  defer/rcuintro.tex             |   2 +-
>>  glossary.tex                   | 176 ++++++++++++++++++++---------------------
>>  glsdict.tex                    |  10 ++-
>>  locking/locking.tex            |   4 +-
>>  perfbook-lt.tex                |  67 +++++++++++++++-
>>  utilities/adjustindexformat.pl |  20 +++++
>>  utilities/runlatex.sh          |   2 +
>>  9 files changed, 189 insertions(+), 96 deletions(-)
>>  create mode 100755 utilities/adjustindexformat.pl
>> --------
>>
>> This is not yet ready for pull.  I need to expand change logs
>> at least.
>>
>> If we were using plain \index{} macro for tagging terms, you could
>> say:
>>
>>     \index{some word|textit}
>>
>> to italicize its page number.
>> However, \IX{some word|textit} does not work.
>>
>> So I need to define a number of macros:
>>
>>   \IXB{}, \IXBh{}{}, ... -> Bold, for that "ff" case
>>   \IXG{}, \IXGh{}{}. ... -> Underline, for definitions in Glossary
>>
>> , and to use one of them where you want to emphasize.
>>
>> The "B" in \IXB came from "Bold", but actual style of emphasis can
>> be changed easily by redefining the \BF{} command.
>> \IXF{} might be a better name.  (Macro names embedded in .tex
>> files need to be stable.)
> 
> I will play with this later today, Pacific Time, but in the meantime I
> just wanted to say that having the most significant page number in an
> index list be bold works just fine.  If we have bold, there is no need
> for italics!

OK!   ;-)

In case you encounter build errors while switching between
WIP- and master branches, "make clean" should help you.

Intermediate index-related files generated on a different branch
might be incompatible.

        Thanks, Akira

> 
> 							Thanx, Paul
> 
>> Furthermore, I have not figured out the way to make those
>> macros generate proper-format index entries in .idx file.
>> This is mostly because I'm not good at low-level TeX programming.
>>
>> So I added adjustindexformat.pl so that it can be amended before
>> fed into "makeindex".
>>
>> I'd like you to have a look at the changes and resulting looks of
>> Index pages.
>>
>> Any feedback is welcome!
>>
>>         Thanks, Akira
>>
>>>
>>> 							Thanx, Paul
>>>

Re: [PATCH RESEND -perfbook 00/10] Index and acronym updates

[Paul E. McKenney]

On Fri, Jan 14, 2022 at 11:13:37PM +0900, Akira Yokosawa wrote:
> On Fri, 14 Jan 2022 05:47:28 -0800,
> Paul E. McKenney wrote:
> > On Fri, Jan 14, 2022 at 07:11:51PM +0900, Akira Yokosawa wrote:
> >> On Fri, 7 Jan 2022 21:07:04 -0800,
> >> Paul E. McKenney wrote:
> >>> On Thu, Jan 06, 2022 at 08:19:45AM -0800, Paul E. McKenney wrote:
> >>>> On Thu, Jan 06, 2022 at 04:29:25PM +0900, Akira Yokosawa wrote:
> >>>>> Hi Paul,
> >>>>>
> >>>>> This is another round of *never-ending* indexing updates.
> >>>>
> >>>> Maintaining indexes is non-trivial, no two ways about it!
> >>>>
> >>>> So special thanks for this series!
> >>>>
> >>>> At some point, for the index entries with lots of references, it may
> >>>> be necesary to flag the most important references.  I sometimes see
> >>>> such entries italicized or marked with "ff", though I freely confess
> >>>> that I have no idea what the rationale for "ff" might be.
> >>>
> >>> And I did find this.  The "ff" stands for "folios following", where
> >>> "folio" is used in the sense of "page".  So "368 ff" means "page 368
> >>> and some number of subsequent pages."
> >>>
> >>> I have spent most of my life fooled into thinking that "ff" indicated
> >>> the most significant page for a given index item.  But there is some
> >>> connection, at least assuming that a longer discussion of a given term
> >>> is a more significant discussion of that term.  ;-)
> >>
> >> So, prompted by your comment, I'm experimenting change of page number
> >> styles referenced in index.
> >>
> >> You can see a WIP tree at:
> >>
> >> --------
> >> The following changes since commit 6eca56ccde0839f4ea81c5f02ddbe4c7c97e225f:
> >>
> >>   Fix a typo in Bibliography (2022-01-12 09:48:13 -0800)
> >>
> >> are available in the Git repository at:
> >>
> >>   https://github.com/akiyks/perfbook.git tags/WIP-index-page-style-2022.01.14
> >>
> >> for you to fetch changes up to cc9e388aee6cd72ed757fa0ec193b8e35f2bbaff:
> >>
> >>   index: Retouch prenote layout (2022-01-14 17:41:30 +0900)
> >>
> >> ----------------------------------------------------------------
> >> Akira Yokosawa (6):
> >>       Initial indexformat support
> >>       locking, defer: POC of bold face page number in index
> >>       defer: POC of hierarchical index with modifier part's case preserved
> >>       index: Add prenotes of legends in Index pages
> >>       index, glossary: Add underline for pages in Glossary
> >>       index: Retouch prenote layout
> >>
> >>  defer/rcu.tex                  |   2 +-
> >>  defer/rcufundamental.tex       |   2 +-
> >>  defer/rcuintro.tex             |   2 +-
> >>  glossary.tex                   | 176 ++++++++++++++++++++---------------------
> >>  glsdict.tex                    |  10 ++-
> >>  locking/locking.tex            |   4 +-
> >>  perfbook-lt.tex                |  67 +++++++++++++++-
> >>  utilities/adjustindexformat.pl |  20 +++++
> >>  utilities/runlatex.sh          |   2 +
> >>  9 files changed, 189 insertions(+), 96 deletions(-)
> >>  create mode 100755 utilities/adjustindexformat.pl
> >> --------
> >>
> >> This is not yet ready for pull.  I need to expand change logs
> >> at least.
> >>
> >> If we were using plain \index{} macro for tagging terms, you could
> >> say:
> >>
> >>     \index{some word|textit}
> >>
> >> to italicize its page number.
> >> However, \IX{some word|textit} does not work.
> >>
> >> So I need to define a number of macros:
> >>
> >>   \IXB{}, \IXBh{}{}, ... -> Bold, for that "ff" case
> >>   \IXG{}, \IXGh{}{}. ... -> Underline, for definitions in Glossary
> >>
> >> , and to use one of them where you want to emphasize.
> >>
> >> The "B" in \IXB came from "Bold", but actual style of emphasis can
> >> be changed easily by redefining the \BF{} command.
> >> \IXF{} might be a better name.  (Macro names embedded in .tex
> >> files need to be stable.)
> > 
> > I will play with this later today, Pacific Time, but in the meantime I
> > just wanted to say that having the most significant page number in an
> > index list be bold works just fine.  If we have bold, there is no need
> > for italics!
> 
> OK!   ;-)
> 
> In case you encounter build errors while switching between
> WIP- and master branches, "make clean" should help you.

I cheated and just cloned your repository separately.  ;-)

> Intermediate index-related files generated on a different branch
> might be incompatible.

So underlined is the glossary and bold is a primary reference.

Looks quite reasonable to me, thank you!

One other option for the glossary is to just give the page-number
range in the note at the beginning of the glossary.  However, the
underlining does seem more convenient for the reader.

Should that note be shortened?

	*Bold*: Major reference.
	_Underline_: Definition.

Given that there are examples of both on the first page, there should
not be too much confusion.  (Famous last words...)

							Thanx, Paul

>         Thanks, Akira
> 
> > 
> > 							Thanx, Paul
> > 
> >> Furthermore, I have not figured out the way to make those
> >> macros generate proper-format index entries in .idx file.
> >> This is mostly because I'm not good at low-level TeX programming.
> >>
> >> So I added adjustindexformat.pl so that it can be amended before
> >> fed into "makeindex".
> >>
> >> I'd like you to have a look at the changes and resulting looks of
> >> Index pages.
> >>
> >> Any feedback is welcome!
> >>
> >>         Thanks, Akira
> >>
> >>>
> >>> 							Thanx, Paul
> >>>

Re: [PATCH RESEND -perfbook 00/10] Index and acronym updates

[Akira Yokosawa]

On Fri, 14 Jan 2022 13:41:51 -0800,
Paul E. McKenney wrote:
> On Fri, Jan 14, 2022 at 11:13:37PM +0900, Akira Yokosawa wrote:
>> On Fri, 14 Jan 2022 05:47:28 -0800,
>> Paul E. McKenney wrote:
>>> On Fri, Jan 14, 2022 at 07:11:51PM +0900, Akira Yokosawa wrote:
>>>> On Fri, 7 Jan 2022 21:07:04 -0800,
>>>> Paul E. McKenney wrote:
>>>>> On Thu, Jan 06, 2022 at 08:19:45AM -0800, Paul E. McKenney wrote:
>>>>>> On Thu, Jan 06, 2022 at 04:29:25PM +0900, Akira Yokosawa wrote:
>>>>>>> Hi Paul,
>>>>>>>
>>>>>>> This is another round of *never-ending* indexing updates.
>>>>>>
>>>>>> Maintaining indexes is non-trivial, no two ways about it!
>>>>>>
>>>>>> So special thanks for this series!
>>>>>>
>>>>>> At some point, for the index entries with lots of references, it may
>>>>>> be necesary to flag the most important references.  I sometimes see
>>>>>> such entries italicized or marked with "ff", though I freely confess
>>>>>> that I have no idea what the rationale for "ff" might be.
>>>>>
>>>>> And I did find this.  The "ff" stands for "folios following", where
>>>>> "folio" is used in the sense of "page".  So "368 ff" means "page 368
>>>>> and some number of subsequent pages."
>>>>>
>>>>> I have spent most of my life fooled into thinking that "ff" indicated
>>>>> the most significant page for a given index item.  But there is some
>>>>> connection, at least assuming that a longer discussion of a given term
>>>>> is a more significant discussion of that term.  ;-)
>>>>
>>>> So, prompted by your comment, I'm experimenting change of page number
>>>> styles referenced in index.
>>>>
>>>> You can see a WIP tree at:
>>>>
>>>> --------
>>>> The following changes since commit 6eca56ccde0839f4ea81c5f02ddbe4c7c97e225f:
>>>>
>>>>   Fix a typo in Bibliography (2022-01-12 09:48:13 -0800)
>>>>
>>>> are available in the Git repository at:
>>>>
>>>>   https://github.com/akiyks/perfbook.git tags/WIP-index-page-style-2022.01.14
>>>>
>>>> for you to fetch changes up to cc9e388aee6cd72ed757fa0ec193b8e35f2bbaff:
>>>>
>>>>   index: Retouch prenote layout (2022-01-14 17:41:30 +0900)
>>>>
>>>> ----------------------------------------------------------------
>>>> Akira Yokosawa (6):
>>>>       Initial indexformat support
>>>>       locking, defer: POC of bold face page number in index
>>>>       defer: POC of hierarchical index with modifier part's case preserved
>>>>       index: Add prenotes of legends in Index pages
>>>>       index, glossary: Add underline for pages in Glossary
>>>>       index: Retouch prenote layout
>>>>
>>>>  defer/rcu.tex                  |   2 +-
>>>>  defer/rcufundamental.tex       |   2 +-
>>>>  defer/rcuintro.tex             |   2 +-
>>>>  glossary.tex                   | 176 ++++++++++++++++++++---------------------
>>>>  glsdict.tex                    |  10 ++-
>>>>  locking/locking.tex            |   4 +-
>>>>  perfbook-lt.tex                |  67 +++++++++++++++-
>>>>  utilities/adjustindexformat.pl |  20 +++++
>>>>  utilities/runlatex.sh          |   2 +
>>>>  9 files changed, 189 insertions(+), 96 deletions(-)
>>>>  create mode 100755 utilities/adjustindexformat.pl
>>>> --------
>>>>
>>>> This is not yet ready for pull.  I need to expand change logs
>>>> at least.
>>>>
>>>> If we were using plain \index{} macro for tagging terms, you could
>>>> say:
>>>>
>>>>     \index{some word|textit}
>>>>
>>>> to italicize its page number.
>>>> However, \IX{some word|textit} does not work.
>>>>
>>>> So I need to define a number of macros:
>>>>
>>>>   \IXB{}, \IXBh{}{}, ... -> Bold, for that "ff" case
>>>>   \IXG{}, \IXGh{}{}. ... -> Underline, for definitions in Glossary
>>>>
>>>> , and to use one of them where you want to emphasize.
>>>>
>>>> The "B" in \IXB came from "Bold", but actual style of emphasis can
>>>> be changed easily by redefining the \BF{} command.
>>>> \IXF{} might be a better name.  (Macro names embedded in .tex
>>>> files need to be stable.)
>>>
>>> I will play with this later today, Pacific Time, but in the meantime I
>>> just wanted to say that having the most significant page number in an
>>> index list be bold works just fine.  If we have bold, there is no need
>>> for italics!
>>
>> OK!   ;-)
>>
>> In case you encounter build errors while switching between
>> WIP- and master branches, "make clean" should help you.
> 
> I cheated and just cloned your repository separately.  ;-)
> 
>> Intermediate index-related files generated on a different branch
>> might be incompatible.
> 
> So underlined is the glossary and bold is a primary reference.
> 
> Looks quite reasonable to me, thank you!

Glad to know you like it! 

> 
> One other option for the glossary is to just give the page-number
> range in the note at the beginning of the glossary.  However, the
> underlining does seem more convenient for the reader.

The underlining was to show you that two or more emphasis style
is possible if necessary.  But I agree it is convenient.
Also, it makes terms without glossary entries more obvious.
You might find a term you'd like to add into glossary.

> 
> Should that note be shortened?
> 
> 	*Bold*: Major reference.
> 	_Underline_: Definition.
> 
> Given that there are examples of both on the first page, there should
> not be too much confusion.  (Famous last words...)

Yes, that should be enough.
I tend to be verbose composing in English...

Will respin and expand changelogs of other commits.

        Thanks, Akira

> 
> 							Thanx, Paul
> 
>>         Thanks, Akira
>>
>>>
>>> 							Thanx, Paul
>>>
>>>> Furthermore, I have not figured out the way to make those
>>>> macros generate proper-format index entries in .idx file.
>>>> This is mostly because I'm not good at low-level TeX programming.
>>>>
>>>> So I added adjustindexformat.pl so that it can be amended before
>>>> fed into "makeindex".
>>>>
>>>> I'd like you to have a look at the changes and resulting looks of
>>>> Index pages.
>>>>
>>>> Any feedback is welcome!
>>>>
>>>>         Thanks, Akira
>>>>
>>>>>
>>>>> 							Thanx, Paul
>>>>>