Merge pull request #2781 from madeline-underwood/threads

Threads_reviewed

Author: jasonrandrews

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

@@ -1,32 +1,35 @@
 ---
-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
 
 ### Tags
-skilllevels: Introductory
+skilllevels: Advanced
 subjects: Performance and Architecture
 armips:
     - Neoverse
 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:
 

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

@@ -8,21 +8,21 @@ layout: learningpathall
 
 ## Create a single-threaded Python benchmark
 
-Now that you have a program that utilizes all available CPU cores, you'll create a single-threaded program that's sensitive to execution variations. This simulates scenarios like a log ingesting process or a single-threaded consumer that needs to maintain a steady pace.
+Create a single-threaded program that's sensitive to execution variations. This simulates scenarios like a log ingesting process or a single-threaded consumer that needs to maintain a steady pace.
 
 Check that you have Python installed:
 
 ```bash
 python --version
 ```
 
-You should see the version of Python:
+The output is similar to:
 
 ```output
 Python 3.12.3
 ```
 
-If Python isn't installed, use your Linux package manager to install it or refer to the  [Python downloads page](https://www.python.org/downloads/).
+If Python isn't installed, use your Linux package manager to install it or see the [Python downloads page](https://www.python.org/downloads/).
 
 Next, create a virtual environment to install packages without interfering with system packages:
 
@@ -32,7 +32,7 @@ source venv/bin/activate
 pip install matplotlib
 ```
 
-Use an editor to create a file named `single_threaded_python_script.py` with the following code. This script repeatedly measures the execution time of a computational function and writes the results to `data.txt`. It then generates time-series graphs to illustrate the effects of thread pinning:
+Create a file named `single_threaded_python_script.py` with the following code. This script measures the execution time of a computational function, writes results to `data.txt`, and generates time-series graphs to illustrate the effects of thread pinning:
 
 ```python
 #!/usr/bin/env python3
@@ -119,7 +119,7 @@ chmod +x single_threaded_python_script.py
 
 ## Compare thread pinning strategies
 
-You'll explore three different scenarios to understand the trade-offs of thread pinning:
+Explore three different scenarios to understand the trade-offs of thread pinning:
 
 1. Free: The operating system allocates both programs to any of four cores
 2. Shared-pinned: The Python script is pinned to core 0, but `prog` can run on any core
@@ -149,9 +149,9 @@ wait
 
 #### Shared script
 
-The next script pins the Python script to core 0, while `prog` can use any of the first four cores:
+The next script pins the Python script to core 0, while `prog` can use any of the first four cores.
 
-Use an editor to create a file named `shared-pinned.sh` with the following code:
+Create a file named `shared-pinned.sh` with the following code:
 
 ```bash
 #!/bin/bash
@@ -167,9 +167,9 @@ wait
 
 #### Exclusive script
 
-The last one gives the Python script exclusive access to core 0, and `prog` uses cores 1-3:
+The last one gives the Python script exclusive access to core 0, and `prog` uses cores 1-3.
 
-Use a text editor to create a file named `exclusive.sh` with the following code:
+Create a file named `exclusive.sh` with the following code:
 
 ```bash
 #!/bin/bash
@@ -198,7 +198,7 @@ chmod +x free-script.sh shared-pinned.sh exclusive.sh
 
 The terminal output shows the execution time for `prog` under the three scenarios. The Python script also generates three files: `Free.jpg`, `Exclusive.jpg`, and `Shared.jpg`.
 
-As the terminal output below shows, the `free-script.sh` scenario (where the Linux scheduler assigns threads to cores without restriction) completes `prog` the fastest at 5.8 seconds. The slowest execution occurs when the Python script has exclusive access to CPU 0, which is expected because you've constrained `prog` to fewer cores:
+The terminal output shows the `free-script.sh` scenario (where the Linux scheduler assigns threads to cores without restriction) completes `prog` the fastest at 5.8 seconds. The slowest execution occurs when the Python script has exclusive access to CPU 0, which is expected because `prog` is constrained to fewer cores:
 
 ```output
 Answer = 3.14159        5 iterations took 5838 milliseconds
@@ -210,21 +210,21 @@ However, this represents a trade-off with the Python script's performance.
 
 ### Free scenario results
 
-Looking at `Free.jpg`, you can see periodic zones of high latency (3.5 ms) that likely occur when there's contention between `prog` and the Python script:
+The `Free.jpg` graph shows periodic zones of high latency (3.5 ms) that likely occur when there's contention between `prog` and the Python script:
 
-![Time-series graph showing execution time varying between 0.5ms and 3.5ms with periodic spikes, indicating contention between processes when both are free to run on any core](free.jpg "Free scenario: both programs can run on any of four cores")
+![Time-series line graph plotting execution time in milliseconds on the y-axis against sample number on the x-axis. The line fluctuates between approximately 0.5ms and 3.5ms, showing periodic spikes and zones of higher latency. The graph has a grid background and is titled 'Free'. The pattern indicates contention between processes when both can run on any core](free.jpg "Free scenario: both programs can run on any of four cores")
 
 ### Shared-pinned scenario results
 
-When pinning the Python script to core 0 while `prog` remains free to use any cores, you observe similar behavior:
+When pinning the Python script to core 0 while `prog` remains free to use any cores, the behavior is similar:
 
-![Time-series graph showing execution time with similar periodic spikes as the free scenario, indicating continued contention despite pinning the Python script](pinned_shared.jpg "Shared-pinned scenario: Python script pinned to core 0, prog free to run on any core")
+![Time-series line graph plotting execution time in milliseconds against sample number. The line shows similar behavior to the free scenario with fluctuations between approximately 0.5ms and 3.5ms and periodic spikes. The graph has a grid background and is titled 'Shared'. The pattern shows continued contention despite pinning the Python script to a specific core](pinned_shared.jpg "Shared-pinned scenario: Python script pinned to core 0, prog free to run on any core")
 
 ### Exclusive scenario results
 
-When the Python script has exclusive access to core 0, you observe more consistent execution time around 0.49 ms because the script doesn't contend with any other demanding processes:
+When the Python script has exclusive access to core 0, the execution time is more consistent around 0.49 ms because the script doesn't contend with any other demanding processes:
 
-![Time-series graph showing consistent execution time around 0.49ms with minimal variation, demonstrating stable performance when the Python script has exclusive core access](exclusive.jpg "Exclusive scenario: Python script has exclusive access to core 0, prog runs on cores 1-3")
+![Time-series line graph plotting execution time in milliseconds against sample number. The line shows consistent, stable execution time around 0.49ms with minimal variation throughout the entire sample range. The graph has a grid background and is titled 'Exclusively Pinned'. The flat, steady pattern demonstrates stable performance when the Python script has exclusive access to a dedicated core](exclusive.jpg "Exclusive scenario: Python script has exclusive access to core 0, prog runs on cores 1-3")
 
 ## Understanding the trade-offs
 
@@ -238,10 +238,10 @@ Multiple factors influence this behavior, including the Linux scheduler algorith
 
 ## What you've accomplished and what's next
 
-In this section, you've:
+In this section:
 - Created a single-threaded Python benchmark that measures execution time variations
 - Used `taskset` to pin processes to specific CPU cores
 - Compared three thread pinning strategies: free, shared-pinned, and exclusive
 - Analyzed the trade-offs between throughput and latency consistency
 
-In the next section, you'll learn how to use source code modifications and environment variables to control thread affinity programmatically.
+Next, you learn how to control thread affinity programmatically using source code modifications.