Refactor CPU affinity learning path content for clarity and detail

Author: madeline-underwood

content/learning-paths/servers-and-cloud-computing/pinning-threads/_index.md

@@ -1,21 +1,21 @@
 ---
-title: Getting Started with CPU Affinity
-
-draft: true
-cascade:
-    draft: true
+title: Optimize application performance with CPU affinity
 
 minutes_to_complete: 30
 
-who_is_this_for: Developers, performance engineers and system administrators, looking to fine-tune the performance of their workload on many-core Arm-based systems.
+who_is_this_for: This is an advanced topic for developers, performance engineers, and system administrators looking to fine-tune the performance of their workload on many-core Arm-based systems.
 
 learning_objectives: 
-    - Create CPU Sets and implement directly into sourcecode
-    - Understand the performance tradeoff when pinning threads with CPU affinity masks
+    - Pin threads to specific CPU cores using taskset and source code modifications
+    - Measure cache performance improvements from thread pinning using perf
+    - Evaluate performance trade-offs between throughput and latency consistency
+    - Implement CPU affinity strategies for co-located workloads
 
 prerequisites:
-    - Intermediate understanding of multi-threaded object-orientated programming in C++ and Python
-    - Foundational understanding of build systems and computer architecture
+    - An Arm Linux system with four or more CPU cores
+    - Experience with multi-threaded programming in C++ and Python
+    - Understanding of build systems and computer architecture concepts
+    - Familiarity with Linux command-line tools
 
 author: Kieran Hejmadi
 
@@ -27,6 +27,9 @@ armips:
 tools_software_languages:
     - C++
     - Python
+    - taskset
+    - perf
+    - Google Benchmark
 operatingsystems:
     - Linux
 
@@ -35,6 +38,22 @@ further_reading:
         title: Taskset Manual  
         link: https://man7.org/linux/man-pages/man1/taskset.1.html
         type: documentation
+    - resource:
+        title: pthread_setaffinity_np Manual
+        link: https://man7.org/linux/man-pages/man3/pthread_setaffinity_np.3.html
+        type: documentation
+    - resource:
+        title: NUMA Deep Dive
+        link: https://frankdenneman.nl/2016/07/07/numa-deep-dive-part-1-uma-numa/
+        type: documentation
+    - resource:
+        title: Linux Scheduler Documentation
+        link: https://www.kernel.org/doc/html/latest/scheduler/index.html
+        type: documentation
+    - resource:
+        title: Get started with Arm-based cloud instances
+        link: /learning-paths/servers-and-cloud-computing/csp/
+        type: website
 
 
 

content/learning-paths/servers-and-cloud-computing/pinning-threads/background_info.md

@@ -1,35 +1,35 @@
 ---
-title: Thread pinning fundamentals
+title: Understand thread pinning and CPU affinity
 weight: 2
 
 ### FIXED, DO NOT MODIFY
 layout: learningpathall
 ---
 
-## CPU affinity
+## Explore CPU affinity
 
 CPU affinity is the practice of binding a process or thread to a specific CPU core or set of cores. This tells the operating system scheduler where that work is allowed to run. By default, the Linux scheduler dynamically migrates threads across cores to balance load and maximize overall throughput. Pinning overrides this behavior by constraining execution to a chosen set of cores.
 
-## Pinning
+## Identify use cases for thread pinning
 
 Pinning is most often used as a fine-tuning technique for workloads that aim to consume as many CPU cycles as possible while running alongside other demanding applications. Scientific computing pipelines and real-time analytics frequently fall into this category. 
 
 Applications that pin processes to specific cores are often sensitive to latency variation rather than just average throughput. They may also have intricate memory access patterns. Pinning can reduce execution noise and provide more consistent behavior or better memory access patterns under load.
 
-## Memory locality 
+## Improve memory locality on NUMA systems
 
 Memory locality provides another important motivation for pinning. On modern systems with Non-Uniform Memory Access (NUMA) architectures, different cores have varying memory access times and characteristics. The performance depends on where the data is fetched from.
 
-For example, in a server with two CPU sockets that appears as a single processor, memory access times differ depending on which core you use. By pinning threads to cores that are close to the memory they use and allocating memory accordingly, you can reduce memory access latency and improve bandwidth.
+For example, in a server with two CPU sockets that appears as a single processor, memory access times differ depending on which core you use. By pinning threads to cores that are close to the memory they use and allocating memory accordingly, you reduce memory access latency and improve bandwidth.
 
-## Setting affinity
+## Choose methods to set CPU affinity
 
 You can set affinity directly in source code using system calls. Many parallel frameworks expose higher-level controls, such as OpenMP affinity settings, that manage thread placement automatically. 
 
 Alternatively, at runtime, system administrators can pin existing processes using utilities like `taskset` or launch applications with `numactl` to control both CPU and memory placement without modifying code.
 
-## Conclusion
+## Evaluate trade-offs of thread pinning
 
-Pinning is a tradeoff. It can improve determinism and locality, but it can also reduce flexibility and hurt performance if the chosen layout isn't optimal or if system load changes. Over-constraining the scheduler may lead to idle cores while pinned threads contend unnecessarily. 
+Thread pinning is a trade-off. It can improve determinism and locality, but it can also reduce flexibility and hurt performance if the chosen layout isn't optimal or if system load changes. Over-constraining the scheduler may lead to idle cores while pinned threads contend unnecessarily. 
 
 As a general rule, rely on the operating system scheduler initially and introduce pinning only when you're looking to fine-tune performance after measuring baseline behavior.

content/learning-paths/servers-and-cloud-computing/pinning-threads/setup.md

@@ -12,11 +12,11 @@ This Learning Path works on any Arm Linux system with four or more CPU cores.
 
 For example, you can use an AWS Graviton 3 `m7g.4xlarge` instance running Ubuntu 24.04 LTS, based on the Arm Neoverse V1 architecture. 
 
-If you're unfamiliar with creating a cloud instance, refer to [Get started with Arm-based cloud instances](/learning-paths/servers-and-cloud-computing/csp/).
+If you're unfamiliar with creating a cloud instance, see [Get started with Arm-based cloud instances](/learning-paths/servers-and-cloud-computing/csp/).
 
 The `m7g.4xlarge` instance has a uniform processor architecture, so there's no difference in memory or CPU core performance across the cores. 
 
-On Linux, you can check this with the following command:
+On Linux, check this with the following command:
 
 ```bash
 lscpu | grep -i numa
@@ -57,9 +57,9 @@ Finally, install the Linux perf utility for measuring performance. See the [Linu
 
 ## Create a CPU-intensive example program
 
-To demonstrate CPU affinity, you'll create a program that heavily utilizes all available CPU cores. This example repeatedly calculates the [Leibniz equation](https://en.wikipedia.org/wiki/Leibniz_formula_for_%CF%80) to compute the value of Pi. This is a computationally inefficient algorithm to calculate Pi, and you'll split the work across many threads.
+To demonstrate CPU affinity, you'll create a program that heavily utilizes all available CPU cores. This example repeatedly calculates the [Leibniz equation](https://en.wikipedia.org/wiki/Leibniz_formula_for_%CF%80) to compute the value of Pi. This is a computationally inefficient algorithm to calculate Pi, and the work is split across many threads.
 
-Use an editor to create a file named `use_all_cores.cpp` with the code below:
+Create a file named `use_all_cores.cpp` with the code below. This program spawns multiple threads that calculate Pi using the Leibniz formula:
 
 ```cpp
 #include <vector>
@@ -75,7 +75,7 @@ double multiplethreaded_leibniz(int terms, bool use_all_cores){
 
     int NUM_THREADS = 2; // use 2 cores by default
     if (use_all_cores){
-        NUM_THREADS = std::thread::hardware_concurrency(); // e.g., 16 for a 16-core, single-threaded processor
+        NUM_THREADS = std::thread::hardware_concurrency(); // for example, 16 for a 16-core, single-threaded processor
     }
     std::vector<double> partial_results(NUM_THREADS);
 
@@ -143,7 +143,7 @@ g++ -O2 --std=c++11 use_all_cores.cpp -o prog
 
 ## Observe CPU utilization
 
-Now that you've compiled the program, you can observe how it utilizes CPU cores. In a separate terminal, use the `top` utility to view the utilization of each core:
+Observe how the compiled program utilizes CPU cores. In a separate terminal, use the `top` utility to view the utilization of each core:
 
 ```bash
 top -d 0.1
@@ -157,9 +157,9 @@ Then run the program in the other terminal:
 ./prog
 ```
 
-![Screenshot of the top command showing CPU utilization with all 16 cores periodically reaching 100% usage, displayed in a dark terminal window with percentage bars for each CPU core](cpu_util.jpg "CPU utilization showing all cores being used")
+![Terminal output showing the top command displaying system resource usage. Sixteen CPU cores labeled CPU0 through CPU15 are shown with horizontal percentage bars. Most cores show near 100% utilization with full green bars. The display includes columns for %Cpu(s), memory usage, and process information in a dark theme terminal window alt-txt#center](cpu_util.jpg "CPU utilization showing all cores being used")
 
-You should observe all cores on your system being periodically utilized up to 100% and then dropping to idle until the program exits.
+All cores on your system are periodically utilized up to 100% and then drop to idle until the program exits.
 
 ## What you've accomplished and what's next
 

content/learning-paths/servers-and-cloud-computing/pinning-threads/thread_affinity.md

@@ -80,7 +80,7 @@ This program has two atomic variables that are aligned on different cache lines
 
 ## Create a program with explicit thread pinning
 
-Now, copy the code below into a new file named `thread_affinity.cpp`:
+Create a file named `thread_affinity.cpp` with the code below. This program uses `pthread_setaffinity_np` to pin threads to specific CPU cores:
 
 ```cpp
 #include <benchmark/benchmark.h>
@@ -178,7 +178,7 @@ perf stat -e L1-dcache-loads,L1-dcache-load-misses ./thread-affinity
 
 ## Analyze the performance results
 
-Inspecting the output below, you can see that the `L1-dcache-load-misses` metric (which occurs when the CPU core doesn't have an up-to-date version of the data in the L1 data cache and must perform an expensive operation to fetch data from a different location) reduces from approximately 7.84% to approximately 0.6% as a result of thread pinning. 
+The output shows the `L1-dcache-load-misses` metric reduces from approximately 7.84% to approximately 0.6% as a result of thread pinning. This metric measures how often the CPU core doesn't have an up-to-date version of data in the L1 data cache and must perform an expensive operation to fetch data from a different location. 
 
 This results in a significant reduction in function execution time, dropping from 10.7 ms to 3.53 ms: