Review C++ memory model Learning Path

Author: jasonrandrews

content/learning-paths/servers-and-cloud-computing/arm-cpp-memory-model/1.md

@@ -16,21 +16,21 @@ You can think of memory ordering as falling into four broad categories:
 
 1. **Source Code Order** - the exact sequence in which you write statements. This is the most intuitive view because it directly reflects how code appears to you.
 
-Here is an example:
+    Here is an example:
 
-```output
-int x = 5; // A
-int z = x * 5; // B
-int y = 42; // C 
-```
+    ```output
+    int x = 5; // A
+    int z = x * 5; // B
+    int y = 42; // C 
+    ```
 
 2. **Program Order** - the logical sequence that the compiler recognizes, and it might rearrange or optimize instructions under certain constraints to create a program that executes in fewer cycles. Although your source code lists statements in a particular order, the compiler can restructure them if it deems it safe. For example, the pseudo-assembly below reorders the source instructions: 
 
-```output
-LDR R1 #5 // A
-LDR R2 #42 // C
-MULT R3, #R1, #5 // B
-```
+    ```output
+    LDR R1 #5 // A
+    LDR R2 #42 // C
+    MULT R3, #R1, #5 // B
+    ```
 
 3. **Execution Order** - this is the order in which the hardware actually issues and executes instructions. Modern CPUs often employ techniques to improve instruction-level parallelism such as out-of-order execution and speculation for performance. For instance, on an Arm-based system, you might see instructions issued in different order during runtime. The subtle difference between program order and execution order is that program order refers to the sequence seen in the binary whereas execution is the order in which those instructions are actually issued and retired. Even though the instructions are listed in one order, the CPU might reorder their micro-operations as long as it respects dependencies.
 

content/learning-paths/servers-and-cloud-computing/arm-cpp-memory-model/2.md

@@ -14,13 +14,13 @@ The single-threaded world was simpler: you wrote code, the compiler safely reord
 
 ### Expanding the memory model for multiple threads
 
-When multi threading programming gained traction, compilers and CPUs needed precise rules about what reordering is allowed. This is where the formalized C++ memory model, introduced in C++11, steps in. Prior to C++11, concurrency in C++ was partially specified and relied on platform-specific behavior. Now, the language standard includes well-defined semantics ensuring that concurrent code can rely on a set of guaranteed rules.
+When multi-threaded programming gained traction, compilers and CPUs needed precise rules about what reordering is allowed. This is where the formalized C++ memory model, introduced in C++11, steps in. Prior to C++11, concurrency in C++ was partially specified and relied on platform-specific behavior. Now, the language standard includes well-defined semantics ensuring that concurrent code can rely on a set of guaranteed rules.
 
-Under the new model, if a piece of data is shared between threads without proper synchronization, you can no longer assume it behaves like single-threaded code. Instead, operations on this shared data may be reordered unless you explicitly prevent it using atomic operations or other synchronization primitives such as mutexes. To ensure correctness, C++ provides an array of memory ordering options (such as `std::memory_order_relaxed`, `std::memory_order_acquire`, and `std::memory_order_release`) that govern how loads and stores can be observed in a multi-threaded environment. Details can be found on the C++ reference manual. 
+Under the new model, if a piece of data is shared between threads without proper synchronization, you can no longer assume it behaves like single-threaded code. Instead, operations on this shared data may be reordered unless you explicitly prevent it using atomic operations or other synchronization primitives such as mutexes. To ensure correctness, C++ provides an array of memory ordering options (such as `std::memory_order_relaxed`, `std::memory_order_acquire`, and `std::memory_order_release`) that govern how loads and stores can be observed in a multi-threaded environment. Details can be found in the C++ reference manual. 
 
 ## C++ atomic memory ordering
 
-In C++, `std::memory_order` atomic operations allow developers to specify how memory accesses, including regular, non-atomic memory accesses are ordered among atomic operation. Choosing the right memory order is crucial for balancing performance and correctness. Assume we have 2 atomic integers with initial values of 0:
+In C++, `std::memory_order` atomic operations allow developers to specify how memory accesses, including regular, non-atomic memory accesses are ordered among atomic operations. Choosing the right memory order is crucial for balancing performance and correctness. Assume we have 2 atomic integers with initial values of 0:
 
 ```cpp
 std::atomic<int> x{0};
@@ -64,5 +64,5 @@ while (atomic_load(ptr, memory_order_acquire) is null) { } // Acquire: wait unti
 
 Sequential consistency, `memory_order_seq_cst` is the strongest order and the default ordering if nothing is specified. 
 
-There are several other memory ordering possibilities. For information on all possible memory ordering possibilities in the C++11 standard and their nuances, please refer to the [C++ reference](https://en.cppreference.com/w/cpp/atomic/memory_order).
+There are several other memory ordering possibilities. For information on all memory ordering possibilities in the C++11 standard and their nuances, please refer to the [C++ reference](https://en.cppreference.com/w/cpp/atomic/memory_order).
 

content/learning-paths/servers-and-cloud-computing/arm-cpp-memory-model/3.md

@@ -10,15 +10,15 @@ layout: learningpathall
 
 Due to the differences in the hardware memory ordering, as explained in the earlier sections, source code written for x86 can behave differently when ported to Arm. 
 
-To demonstrate this, this Learning Path walks you through a simple example that is run on both x86 and Arm cloud instance. 
+To demonstrate this, this section walks you through a simple example that is run on both an x86 and an Arm cloud instance. 
 
 ### Get Started 
 
-Start an Arm-based cloud instance. This example uses a `t4g.xlarge` AWS instance running Ubuntu 22.04 LTS, but you can use other instances types. 
+Start an Arm-based cloud instance. This example uses a `t4g.xlarge` AWS instance running Ubuntu 22.04 LTS, but you can use other instance types. 
 
 If you are new to cloud-based virtual machines, see [Get started with Servers and Cloud Computing](/learning-paths/servers-and-cloud-computing/intro/). 
 
-First confirm you are using a Arm-based instance with the following command.
+First, confirm you are using a Arm-based instance with the following command.
 
 ```bash
 uname -m
@@ -115,12 +115,14 @@ Subtle issues can surface under specific workloads, making them challenging to d
 
 Due to the stronger memory model in x86 processors, programs not adhering to the C++ standard might give programmers a false sense of security. To demonstrate this, create an connect to an AWS `t2.2xlarge` instance that uses the x86 architecture. 
 
-Running the following command I can observe the underlying hardware is a Intel Xeon E5-2686 Processor
+Running the command below you observe the underlying hardware is a Intel Xeon E5-2686 Processor.
 
 ```bash
 lscpu | grep -i "Model"
 ```
 
+Here is the output:
+
 ```output
 Model name:                           Intel(R) Xeon(R) CPU E5-2686 v4 @ 2.30GHz
 Model:                                79
@@ -199,7 +201,7 @@ int main() {
 
 ```
 
-Compile and run on the Arm-based machine:
+Compile and run the new code on the Arm-based machine:
 
 ```bash
 g++ correct_memory_ordering.cpp -o correct_memory_ordering -O3

content/learning-paths/servers-and-cloud-computing/arm-cpp-memory-model/4.md

@@ -8,11 +8,11 @@ layout: learningpathall
 
 ## How can I detect infrequent race conditions?
 
-ThreadSanitizer (TSan) is a concurrency bug detection tool that identifies data races in multithreaded programs. By instrumenting code at compile time, `TSan` dynamically tracks memory operations, monitors lock usage, and detects inconsistencies in thread synchronization. When a potential data race is found, `TSan` provides detailed reports to help you debug. 
+ThreadSanitizer (TSan) is a concurrency bug detection tool that identifies data races in multithreaded programs. By instrumenting code at compile time, TSan dynamically tracks memory operations, monitors lock usage, and detects inconsistencies in thread synchronization. When a potential data race is found, TSan provides detailed reports to help you debug. 
 
-Although its runtime overhead can be significant, `TSan` provides valuable insights into concurrency issues often missed by static analysis tools.
+Although its runtime overhead can be significant, TSan provides valuable insights into concurrency issues often missed by static analysis tools.
 
-`TSan` is available in recent versions of the `clang` and `gcc` compilers. 
+TSan is available in recent versions of the `clang` and `gcc` compilers. 
 
 Compile and run the following example using the `clang++` compiler: 
 
@@ -38,7 +38,7 @@ This output highlights a potential data race in the `threadB` function, correspo
 
 ## Does TSan have any limitations? 
 
-While powerful, `TSan` has some notable drawbacks: 
+While powerful, TSan has some notable drawbacks: 
 
 * It identifies concurrency issues only at runtime, meaning code paths not exercised during testing remain unchecked. 
 

content/learning-paths/servers-and-cloud-computing/arm-cpp-memory-model/_index.md

@@ -1,10 +1,6 @@
 ---
 title: Learn about the C++ memory model for porting applications to Arm
 
-draft: true
-cascade:
-    draft: true
-
 minutes_to_complete: 45
 
 who_is_this_for: This is an advanced topic for C++ developers porting applications from x86 to Arm and optimizing performance.
@@ -15,7 +11,7 @@ learning_objectives:
     - Employ best practices for writing C++ on Arm to avoid race conditions.
 
 prerequisites:
-    - Access to an x86 and Arm cloud instance (virtual machine).
+    - Access to an x86 and an Arm cloud instance (virtual machine).
     - Proficiency in C++ programming.
 
 author: Kieran Hejmadi