foxhunt/WAVE_7_8_MEMORY_CORRUPTION_ANALYSIS.md

Wave 7.8: Memory Corruption Analysis - Double Free Bug

Date: 2025-10-15 Severity: CRITICAL Status: ROOT CAUSE IDENTIFIED

---

Executive Summary

Root Cause: Double-free memory corruption in MPSCQueue hazard pointer cleanup logic Location: /home/jgrusewski/Work/foxhunt/trading_engine/src/lockfree/mpsc_queue.rs Affected Lines: 170-183 (Drop impl), 258-276 (HazardPointers::cleanup), 279-282 (HazardPointers Drop)

Impact: SIGABRT crashes with "free(): double free detected in tcache 2" during tests

---

Bug Analysis

The Double-Free Sequence

The bug occurs through this sequence:

1. Node Retirement (Line 150, 227-256):

   • When try_pop() succeeds, it calls self.hazard_pointers.retire(head)
   • This creates a RetiredNode wrapper containing the pointer to the old head node
   • The RetiredNode is added to a linked list for later cleanup

2. Cleanup Triggered (Line 258-276):

   fn cleanup(&self) {
       let head = self.retired.swap(ptr::null_mut(), Ordering::Acquire);
       let mut current = head;
       while !current.is_null() {
           unsafe {
               let node = Box::from_raw(current);  // ← Deallocates RetiredNode
               let _ = Box::from_raw(node.ptr);    // ← Deallocates actual Node<T>
               current = node.next;
           }
       }
   }
   

3. MPSCQueue Drop (Line 170-184):

   impl<T> Drop for MPSCQueue<T> {
       fn drop(&mut self) {
           while self.try_pop().is_some() {}  // ← Drains and retires nodes
   
           let head = self.head.load(Ordering::Relaxed);
           if !head.is_null() {
               unsafe {
                   let _ = Box::from_raw(head);  // ← Deallocates dummy node
               }
           }
       }
   }
   

4. HazardPointers Drop (Line 279-282):

   impl<T> Drop for HazardPointers<T> {
       fn drop(&mut self) {
           self.cleanup();  // ← Attempts to free already-freed nodes!
       }
   }
   

The Problem

Double-Free Scenario 1: Dummy Node

• The MPSCQueue::Drop explicitly frees the dummy node (line 180)
• If the dummy node was ever retired to hazard pointers (which it shouldn't be but code doesn't prevent)
• HazardPointers::cleanup() will try to free it again → SIGABRT

Double-Free Scenario 2: Race with cleanup threshold

• try_pop() retires a node at line 150
• Line 253: if count > 100 { self.cleanup(); } triggers cleanup
• Cleanup frees all retired nodes including the one just retired
• Later, HazardPointers::drop() calls cleanup() again
• But the retired list was already cleared! The nodes are already freed!
• Wait, this should be OK because swap(ptr::null_mut()) empties the list...

ACTUAL DOUBLE-FREE ROOT CAUSE:

Looking more carefully at lines 170-183:

impl<T> Drop for MPSCQueue<T> {
    fn drop(&mut self) {
        // Drain remaining items
        while self.try_pop().is_some() {}  // ← This retires nodes to hazard_pointers

        // Clean up dummy node
        let head = self.head.load(Ordering::Relaxed);
        if !head.is_null() {
            unsafe {
                let _ = Box::from_raw(head);  // ← Frees the dummy node
            }
        }
        // After this, MPSCQueue is dropped
        // Then HazardPointers (member field) is dropped
        // HazardPointers::drop calls cleanup() which frees retired nodes
    }
}

THE BUG: When try_pop() moves head forward (line 146), it retires the OLD head node. If we drain all items, the final head position is at some node N. The dummy node gets freed explicitly at line 180. BUT, if the dummy node was ever the "old head" during a try_pop(), it was retired to the hazard pointer list. Then:

1. Line 180: Dummy node freed explicitly
2. Drop proceeds to hazard_pointers field drop
3. Line 281: HazardPointers::drop() calls cleanup()
4. Line 269: Box::from_raw(node.ptr) tries to free the dummy node AGAIN → DOUBLE FREE

---

Proof of Concept

The bug manifests when:

1. Queue has items
2. Consumer calls try_pop() repeatedly
3. Each successful pop retires the old head (which started as the dummy node)
4. Queue drops, explicitly freeing the dummy node
5. HazardPointers drops, trying to free retired nodes including the dummy → SIGABRT

---

The Fix

Option 1: Never Retire the Dummy Node (RECOMMENDED)

Modify try_pop() to track and skip retiring the dummy node:

pub struct MPSCQueue<T> {
    head: AtomicPtr<Node<T>>,
    tail: AtomicPtr<Node<T>>,
    size: AtomicUsize,
    hazard_pointers: HazardPointers<Node<T>>,
    dummy_node: *mut Node<T>,  // ← Track dummy node pointer
}

impl<T> MPSCQueue<T> {
    pub fn new() -> Self {
        let dummy_node = Box::into_raw(Box::new(Node::empty()));
        Self {
            head: AtomicPtr::new(dummy_node),
            tail: AtomicPtr::new(dummy_node),
            size: AtomicUsize::new(0),
            hazard_pointers: HazardPointers::new(),
            dummy_node,  // ← Store dummy node pointer
        }
    }

    pub fn try_pop(&self) -> Option<T> {
        loop {
            let head = self.head.load(Ordering::Acquire);
            // ... existing logic ...

            if self.head.compare_exchange_weak(head, next, ...).is_ok() {
                // Only retire if it's not the dummy node
                if head != self.dummy_node {  // ← CHECK BEFORE RETIRING
                    self.hazard_pointers.retire(head);
                } else {
                    // Dummy node stays around, will be freed in Drop
                    unsafe { let _ = Box::from_raw(head); }
                }
                self.size.fetch_sub(1, Ordering::Relaxed);
                return data;
            }
        }
    }
}

impl<T> Drop for MPSCQueue<T> {
    fn drop(&mut self) {
        // Drain remaining items (safe now, won't double-retire dummy)
        while self.try_pop().is_some() {}

        // Clean up dummy node - guaranteed not in hazard pointer list
        if !self.dummy_node.is_null() {
            unsafe {
                let _ = Box::from_raw(self.dummy_node);
            }
        }
    }
}

Option 2: Don't Explicitly Free Dummy in Drop

Let the hazard pointer system handle ALL node cleanup:

impl<T> Drop for MPSCQueue<T> {
    fn drop(&mut self) {
        // Drain remaining items
        while self.try_pop().is_some() {}

        // Don't free dummy node here - hazard pointers will handle it
        // The dummy node is already in the retired list from try_pop operations
    }
}

Problem with Option 2: If queue is never used (no pops), dummy node leaks.

Option 3: Clear Hazard Pointers Before Freeing Dummy (SAFEST)

impl<T> Drop for MPSCQueue<T> {
    fn drop(&mut self) {
        // Drain remaining items
        while self.try_pop().is_some() {}

        // Clean up ALL hazard pointers first
        self.hazard_pointers.cleanup();

        // Now safe to free dummy node (not in retired list anymore)
        let head = self.head.load(Ordering::Relaxed);
        if !head.is_null() {
            unsafe {
                let _ = Box::from_raw(head);
            }
        }
        // When hazard_pointers drops, cleanup() finds empty list → no double free
    }
}

---

Recommended Fix: Option 1 (Most Robust)

Option 1 is the cleanest solution because:

1. ✅ No memory leaks (dummy always freed in Drop)
2. ✅ No double-free (dummy never enters hazard pointer list)
3. ✅ Clear ownership semantics (dummy owned by MPSCQueue, other nodes by hazard pointers)
4. ✅ Minimal performance impact (one pointer comparison per pop)

---

Testing the Fix

Valgrind Test

cargo build --package trading_engine --tests
valgrind --leak-check=full --track-origins=yes \
  target/debug/deps/mpsc_queue-* \
  --test test_mpsc_basic_operations

AddressSanitizer Test

RUSTFLAGS="-Z sanitizer=address" \
cargo +nightly test --package trading_engine --lib lockfree::mpsc_queue

Stress Test

# Run multi-threaded test 1000 times to catch race conditions
for i in {1..1000}; do
  cargo test --package trading_engine test_mpsc_multiple_producers || break
  echo "Iteration $i passed"
done

---

Additional Observations

Other Potential Issues

1. LockFreeRingBuffer: Drop implementation (line 197-204) looks correct:

   • Uses dealloc() directly on buffer pointer
   • No double-free risk (only one dealloc per buffer)
   • ✅ SAFE

2. SmallBatchRing: Drop implementation (line 314-320) identical pattern to LockFreeRingBuffer:

   • ✅ SAFE

3. EventRingBuffer: Uses Arc<RwLock<BufferStats>> at line 24:

   • Arc handles reference counting correctly
   • No manual dealloc
   • ✅ SAFE

Why This Bug is Hard to Catch

1. Timing-dependent: Only crashes when queue is dropped after items were popped
2. Silent in single-threaded: May not crash if allocator reuses memory
3. Tcache masking: Modern allocators (tcache) detect it but older code might corrupt silently
4. Test coverage: Basic tests pass because they don't trigger the specific drop sequence

---

Patch Priority

CRITICAL: This bug can cause production crashes in trading engine under these conditions:

• High-frequency order processing (MPSC queue used for event handling)
• Thread pool shutdown sequences
• Service restart scenarios
• Memory pressure situations where allocator is more strict

Estimated Fix Time: 2-4 hours (implement Option 1 + comprehensive testing)

---

Next Steps

1. ✅ Root cause identified
2. ⏳ Implement Option 1 fix
3. ⏳ Add regression test (drop after multiple pops)
4. ⏳ Run valgrind/ASAN verification
5. ⏳ Update all affected tests
6. ⏳ Document the fix in commit message

---

References

• MPSCQueue implementation: trading_engine/src/lockfree/mpsc_queue.rs
• Rust memory safety: https://doc.rust-lang.org/nomicon/
• Hazard pointers: https://en.wikipedia.org/wiki/Hazard_pointer
• Lock-free programming: https://preshing.com/20120612/an-introduction-to-lock-free-programming/