refactor(arch): round 4 - injectable metrics, generic dispatch, and shallow cleanup

- Create OperationMetrics seam with RAII Scope to replace global static
counters in Buffer and CountingAllocator (test isolation, zero-overhead
opt-out via nullptr).
- Extract generic resolve_best<Func>() SIMD runtime dispatcher so CPU
detection logic is no longer coupled to add_arrays.
- Document cache-line allocator vs SIMD-width allocator distinction in
CONTEXT.md and cross-link both headers.
- Delete untestable prefetch_* wrappers from memory_utils.hpp; use
__builtin_prefetch directly in example source.
- Mark ranges_utils.hpp as intentionally-shallow teaching module.
- Archive completed architecture-deepening change.

Generated with [Devin](https://cli.devin.ai/docs)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Author: LessUp

CONTEXT.md

@@ -77,6 +77,16 @@ ARM 平台：NEON (128-bit)
 ### preset-driven build / 预设驱动构建
 使用 CMakePresets.json 统一构建配置，确保本地和 CI 环境一致。
 
+### cache-line allocator / 缓存行对齐分配器
+对齐到缓存行边界（通常 64 字节）的内存分配器，用于消除伪共享。
+参见 `hpc::memory::AlignedAllocator<T, Alignment>`，对齐策略为**编译时常量**。
+
+### SIMD-width allocator / SIMD 宽度对齐分配器
+对齐到 SIMD 向量宽度边界（16/32/64 字节）的内存分配器，用于 SIMD 加载/存储操作。
+参见 `hpc::simd::AlignedAllocator<T>`，对齐策略为**运行时 CPU 特性检测**。
+
+**关键区别**：缓存行分配器服务于多线程并发优化（伪共享消除），SIMD 宽度分配器服务于单线程向量化（对齐加载）。两者独立存在，不共享实现。
+
 ### sanitizer / 消毒器
 运行时检测工具，发现未定义行为和内存错误：
 - **ASAN (AddressSanitizer)**: 检测内存错误（越界、释放后使用等）

examples/02-memory-cache/include/memory_utils.hpp

@@ -2,14 +2,13 @@
  * @file memory_utils.hpp
  * @brief Memory and cache optimization utilities
  *
- * This header provides utilities for memory alignment, cache-friendly
- * data structures, and performance measurement helpers.
+ * This header provides utilities for memory alignment and cache-friendly
+ * data structures.
  *
  * Validates:
  *   - Requirement 2.1: AOS vs SOA Comparison
  *   - Requirement 2.2: False Sharing Demonstration
  *   - Requirement 2.3: Memory Alignment for SIMD
- *   - Requirement 2.4: Prefetch Demonstration
  */
 
 #pragma once
@@ -95,7 +94,13 @@ aligned_unique_ptr<T> make_aligned(std::size_t count,
 //------------------------------------------------------------------------------
 
 /**
- * @brief STL-compatible allocator with custom alignment
+ * @brief Cache-line aligned allocator for STL containers
+ *
+ * Uses a compile-time constant alignment (default: CACHE_LINE_SIZE).
+ * Designed for false-sharing elimination in multi-threaded code.
+ *
+ * See CONTEXT.md: cache-line allocator for the domain rationale.
+ * For SIMD-width alignment, see hpc::simd::AlignedAllocator in simd_utils.hpp.
  */
 template <typename T, std::size_t Alignment = hpc::core::CACHE_LINE_SIZE>
 class AlignedAllocator {
@@ -169,58 +174,4 @@ struct alignas(hpc::core::CACHE_LINE_SIZE) CacheLinePadded {
     const T* operator->() const { return &value; }
 };
 
-//------------------------------------------------------------------------------
-// Prefetch Hints
-//------------------------------------------------------------------------------
-
-/**
- * @brief Prefetch data for reading
- */
-template <typename T>
-inline void prefetch_read(const T* ptr) {
-#if defined(__GNUC__) || defined(__clang__)
-    __builtin_prefetch(ptr, 0, 3);  // Read, high temporal locality
-#elif defined(_MSC_VER)
-    _mm_prefetch(reinterpret_cast<const char*>(ptr), _MM_HINT_T0);
-#endif
-}
-
-/**
- * @brief Prefetch data for writing
- */
-template <typename T>
-inline void prefetch_write(T* ptr) {
-#if defined(__GNUC__) || defined(__clang__)
-    __builtin_prefetch(ptr, 1, 3);  // Write, high temporal locality
-#elif defined(_MSC_VER)
-    _mm_prefetch(reinterpret_cast<const char*>(ptr), _MM_HINT_T0);
-#endif
-}
-
-/**
- * @brief Prefetch with specified locality hint
- * @param locality 0 = non-temporal, 3 = high temporal locality
- */
-template <typename T>
-inline void prefetch(const T* ptr, int locality = 3) {
-#if defined(__GNUC__) || defined(__clang__)
-    __builtin_prefetch(ptr, 0, locality);
-#elif defined(_MSC_VER)
-    switch (locality) {
-        case 0:
-            _mm_prefetch(reinterpret_cast<const char*>(ptr), _MM_HINT_NTA);
-            break;
-        case 1:
-            _mm_prefetch(reinterpret_cast<const char*>(ptr), _MM_HINT_T2);
-            break;
-        case 2:
-            _mm_prefetch(reinterpret_cast<const char*>(ptr), _MM_HINT_T1);
-            break;
-        default:
-            _mm_prefetch(reinterpret_cast<const char*>(ptr), _MM_HINT_T0);
-            break;
-    }
-#endif
-}
-
 }  // namespace hpc::memory

examples/02-memory-cache/src/prefetch.cpp

@@ -18,8 +18,6 @@
 #include <random>
 #include <vector>
 
-#include "memory_utils.hpp"
-
 namespace hpc::memory {
 
 //------------------------------------------------------------------------------
@@ -49,9 +47,11 @@ int64_t sum_with_prefetch(const int64_t* data, size_t n) {
 
     int64_t sum = 0;
     for (size_t i = 0; i < n; ++i) {
-        // Prefetch future data
+        // Prefetch future data (read, high temporal locality)
         if (i + PREFETCH_DISTANCE < n) {
-            prefetch_read(&data[i + PREFETCH_DISTANCE]);
+#if defined(__GNUC__) || defined(__clang__)
+            __builtin_prefetch(&data[i + PREFETCH_DISTANCE], 0, 3);
+#endif
         }
         sum += data[i];
     }
@@ -85,7 +85,9 @@ int64_t sum_random_with_prefetch(const int64_t* data, const size_t* indices, siz
     for (size_t i = 0; i < n; ++i) {
         // Prefetch data for future iterations
         if (i + PREFETCH_DISTANCE < n) {
-            prefetch_read(&data[indices[i + PREFETCH_DISTANCE]]);
+#if defined(__GNUC__) || defined(__clang__)
+            __builtin_prefetch(&data[indices[i + PREFETCH_DISTANCE]], 0, 3);
+#endif
         }
         sum += data[indices[i]];
     }
@@ -122,7 +124,9 @@ int64_t sum_list_with_prefetch(const Node* head) {
     for (const Node* node = head; node != nullptr; node = node->next) {
         // Prefetch next node
         if (node->next != nullptr) {
-            prefetch_read(node->next);
+#if defined(__GNUC__) || defined(__clang__)
+            __builtin_prefetch(node->next, 0, 3);
+#endif
         }
         sum += node->value;
     }

examples/03-modern-cpp/include/buffer.hpp

@@ -16,6 +16,8 @@
 #include <cstring>
 #include <utility>
 
+#include "instrumentation.hpp"
+
 namespace hpc::move_semantics {
 
 /**
@@ -29,51 +31,56 @@ namespace hpc::move_semantics {
  */
 class Buffer {
 public:
-    Buffer() : data_(nullptr), size_(0) {}
+    Buffer() : data_(nullptr), size_(0), metrics_(nullptr) {}
 
-    explicit Buffer(size_t size) : data_(new char[size]), size_(size) {
+    explicit Buffer(size_t size, instrumentation::OperationMetrics* metrics = nullptr)
+        : data_(new char[size]), size_(size), metrics_(metrics) {
         std::memset(data_, 0, size_);
     }
 
     ~Buffer() { delete[] data_; }
 
-    Buffer(const Buffer& other) : data_(nullptr), size_(other.size_) {
+    Buffer(const Buffer& other, instrumentation::OperationMetrics* metrics = nullptr)
+        : data_(nullptr), size_(other.size_), metrics_(metrics ? metrics : other.metrics_) {
         if (size_ > 0) {
             data_ = new char[size_];
             std::memcpy(data_, other.data_, size_);
         }
-        ++copy_count_;
+        notify_copy();
     }
 
     Buffer& operator=(const Buffer& other) {
         if (this != &other) {
             delete[] data_;
             size_ = other.size_;
+            metrics_ = other.metrics_;
             if (size_ > 0) {
                 data_ = new char[size_];
                 std::memcpy(data_, other.data_, size_);
             } else {
                 data_ = nullptr;
             }
-            ++copy_count_;
+            notify_copy();
         }
         return *this;
     }
 
-    Buffer(Buffer&& other) noexcept : data_(other.data_), size_(other.size_) {
+    Buffer(Buffer&& other) noexcept
+        : data_(other.data_), size_(other.size_), metrics_(other.metrics_) {
         other.data_ = nullptr;
         other.size_ = 0;
-        ++move_count_;
+        notify_move();
     }
 
     Buffer& operator=(Buffer&& other) noexcept {
         if (this != &other) {
             delete[] data_;
             data_ = other.data_;
             size_ = other.size_;
+            metrics_ = other.metrics_;
             other.data_ = nullptr;
             other.size_ = 0;
-            ++move_count_;
+            notify_move();
         }
         return *this;
     }
@@ -82,21 +89,20 @@ class Buffer {
     char* data() { return data_; }
     const char* data() const { return data_; }
 
-    static size_t copy_count_;
-    static size_t move_count_;
-
-    static void reset_counts() {
-        copy_count_ = 0;
-        move_count_ = 0;
-    }
-
 private:
     char* data_;
     size_t size_;
-};
+    instrumentation::OperationMetrics* metrics_;
 
-inline size_t Buffer::copy_count_ = 0;
-inline size_t Buffer::move_count_ = 0;
+    void notify_copy() const {
+        if (metrics_)
+            metrics_->record_copy();
+    }
+    void notify_move() const {
+        if (metrics_)
+            metrics_->record_move();
+    }
+};
 
 //------------------------------------------------------------------------------
 // Functions demonstrating copy vs move

examples/03-modern-cpp/include/instrumentation.hpp

@@ -0,0 +1,97 @@
+/**
+ * @file instrumentation.hpp
+ * @brief Operation metrics collection with RAII scope management
+ *
+ * Replaces global static counters (e.g., Buffer::copy_count_,
+ * CountingAllocator::allocation_count_) with an injectable, non-static
+ * seam. Each test or demo creates a local OperationMetrics instance,
+ * passes it to the module under observation, and uses the Scope helper
+ * for automatic lifecycle management.
+ *
+ * Key concepts:
+ * - Injectability: metrics are passed by pointer, not baked into class state
+ * - RAII scope: OperationMetrics::Scope resets on construction, no manual cleanup
+ * - Zero overhead: nullptr means "do not observe"
+ * - Thread-local by default: each scope owns its own counters
+ *
+ * @example
+ *   hpc::instrumentation::OperationMetrics metrics;
+ *   hpc::instrumentation::OperationMetrics::Scope scope(metrics);
+ *   Buffer buf(128, &metrics);
+ *   Buffer copy(buf);  // metrics.copy_count == 1
+ */
+
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+
+namespace hpc::instrumentation {
+
+/**
+ * @brief Generic operation counter for copy/move/allocation events.
+ *
+ * A single seam that replaces the scattered static counters previously
+ * embedded in Buffer and CountingAllocator. By making the counter
+ * external and injectable, tests no longer suffer from order-dependent
+ * state pollution, and benchmarks pay zero overhead when metrics is
+ * nullptr.
+ */
+class OperationMetrics {
+public:
+    size_t copy_count = 0;
+    size_t move_count = 0;
+    size_t allocation_count = 0;
+    size_t deallocation_count = 0;
+    size_t total_bytes_allocated = 0;
+    size_t total_bytes_deallocated = 0;
+
+    /**
+     * @brief Reset all counters to zero.
+     */
+    void reset() noexcept {
+        copy_count = 0;
+        move_count = 0;
+        allocation_count = 0;
+        deallocation_count = 0;
+        total_bytes_allocated = 0;
+        total_bytes_deallocated = 0;
+    }
+
+    /**
+     * @brief RAII scope that resets metrics on entry.
+     *
+     * Guarantees each test block starts from a clean slate without
+     * manual reset_counts() calls.
+     */
+    class Scope {
+    public:
+        explicit Scope(OperationMetrics& m) : metrics_(m) { metrics_.reset(); }
+        ~Scope() = default;
+
+        Scope(const Scope&) = delete;
+        Scope& operator=(const Scope&) = delete;
+        Scope(Scope&&) = delete;
+        Scope& operator=(Scope&&) = delete;
+
+        OperationMetrics& metrics() noexcept { return metrics_; }
+        const OperationMetrics& metrics() const noexcept { return metrics_; }
+
+    private:
+        OperationMetrics& metrics_;
+    };
+
+    // Named event recorders for type safety and locality
+    void record_copy() noexcept { ++copy_count; }
+    void record_move() noexcept { ++move_count; }
+    void record_allocation(size_t bytes) noexcept {
+        ++allocation_count;
+        total_bytes_allocated += bytes;
+    }
+    void record_deallocation(size_t bytes) noexcept {
+        ++deallocation_count;
+        total_bytes_deallocated += bytes;
+    }
+};
+
+}  // namespace hpc::instrumentation

examples/03-modern-cpp/include/ranges_utils.hpp

@@ -1,11 +1,13 @@
 /**
  * @file ranges_utils.hpp
- * @brief C++20 Ranges utility functions
+ * @brief C++20 Ranges comparison utilities (teaching module)
  *
- * This header provides utility functions comparing C++20 ranges
- * with traditional raw loops for performance analysis.
+ * **Note: This is a teaching example module, not production-ready code.**
+ * Each function is intentionally shallow — its interface exposes the
+ * implementation strategy (raw_loop / algorithm / ranges). The value
+ * is in side-by-side comparison, not in abstraction depth.
  *
- * Key concepts:
+ * Key concepts demonstrated:
  * - std::ranges algorithms
  * - Range views (lazy evaluation)
  * - Compiler optimization of ranges