hakmem/LARSON_QUICK_REF.md

# Larson Crash - Quick Reference Card

## TL;DR

**C7 Fix**: ✅ CORRECT (not the problem)
**Larson Crash**: 🔥 Race condition in freelist (unrelated to C7)
**Root Cause**: Non-atomic concurrent access to `TinySlabMeta.freelist`
**Location**: `core/front/tiny_unified_cache.c:172`

---

## Crash Pattern

| Threads | Result | Evidence |
|---------|--------|----------|
| 1 (ST) | ✅ PASS | C7 works perfectly (1.88M - 41.8M ops/s) |
| 2 | ✅ PASS | Usually succeeds (~24.6M ops/s) |
| 3+ | ❌ SEGV | Crashes consistently |

**Conclusion**: Multi-threading race, NOT C7 bug.

---

## Root Cause (1 sentence)

Multiple threads concurrently pop from the same `TinySlabMeta.freelist` without atomics or locks, causing double-pop and corruption.

---

## Race Condition Diagram

```
Thread A                    Thread B
--------                    --------
p = m->freelist (0x1000)    p = m->freelist (0x1000)  ← Same!
next = read(p)              next = read(p)
m->freelist = next ───┐     m->freelist = next ───┐
                      └───── RACE! ─────────────┘
Result: Double-pop, freelist corrupted to 0x6
```

---

## Quick Verification (5 commands)

```bash
# 1. C7 works?
./out/release/bench_random_mixed_hakmem 10000 1024 42  # ✅ Expected: ~1.88M ops/s

# 2. Larson 2T works?
./out/release/larson_hakmem 2 2 100 1000 100 12345 1   # ✅ Expected: ~24.6M ops/s

# 3. Larson 4T crashes?
./out/release/larson_hakmem 4 4 500 10000 1000 12345 1  # ❌ Expected: SEGV

# 4. Check if freelist is atomic
grep "freelist" core/superslab/superslab_types.h | grep -q "_Atomic" && echo "✅ Atomic" || echo "❌ Not atomic"

# 5. Run verification script
./verify_race_condition.sh
```

---

## Fix Options (Choose One)

### Option 1: Atomic (BEST) ⭐
```diff
// core/superslab/superslab_types.h
-    void*    freelist;
+    _Atomic uintptr_t freelist;
```
**Time**: 7-9 hours (2-3h impl + 3-4h audit)
**Pros**: Lock-free, optimal performance
**Cons**: Requires auditing 87 sites

### Option 2: Workaround (FAST) 🏃
```c
// core/front/tiny_unified_cache.c:137
if (tls->meta->owner_tid_low != my_tid_low) {
    tls->ss = NULL;  // Force new slab
}
```
**Time**: 1 hour
**Pros**: Quick, unblocks testing
**Cons**: ~10-15% performance loss

### Option 3: Mutex (SIMPLE) 🔒
```diff
// core/superslab/superslab_types.h
+    pthread_mutex_t lock;
```
**Time**: 2 hours
**Pros**: Simple, guaranteed correct
**Cons**: ~20-30% performance loss

---

## Testing Checklist

- [ ] `bench_random_mixed 1024` → ✅ (C7 works)
- [ ] `larson 2 2 ...` → ✅ (low contention)
- [ ] `larson 4 4 ...` → ❌ (reproduces crash)
- [ ] Apply fix
- [ ] `larson 10 10 ...` → ✅ (no crash)
- [ ] Performance >= 20M ops/s → ✅ (acceptable)

---

## File Locations

| File | Purpose |
|------|---------|
| `LARSON_CRASH_ROOT_CAUSE_REPORT.md` | Full analysis (READ FIRST) |
| `LARSON_DIAGNOSTIC_PATCH.md` | Implementation guide |
| `LARSON_INVESTIGATION_SUMMARY.md` | Executive summary |
| `verify_race_condition.sh` | Automated verification |
| `core/front/tiny_unified_cache.c` | Crash location (line 172) |
| `core/superslab/superslab_types.h` | Fix location (TinySlabMeta) |

---

## Commands to Remember

```bash
# Reproduce crash
./out/release/larson_hakmem 4 4 500 10000 1000 12345 1

# GDB backtrace
gdb -batch -ex "run 4 4 500 10000 1000 12345 1" -ex "bt 20" ./out/release/larson_hakmem

# Find freelist sites
grep -rn "->freelist" core/ --include="*.c" --include="*.h" | wc -l  # 87 sites

# Check C7 protections
grep -rn "class_idx != 0[^&]" core/ --include="*.h" --include="*.c"  # All have && != 7
```

---

## Key Insights

1. **C7 fix is unrelated**: Crashes existed before/after C7 fix
2. **Not C7-specific**: Affects all classes (C0-C7)
3. **MT-only**: Single-threaded tests always pass
4. **Architectural issue**: TLS points to shared metadata
5. **Well-documented**: 3 comprehensive reports created

---

## Next Actions (Priority Order)

1. **P0** (5 min): Run `./verify_race_condition.sh` to confirm
2. **P1** (1 hr): Apply workaround to unblock Larson
3. **P2** (7-9 hrs): Implement atomic fix for production
4. **P3** (future): Consider architectural refactoring

---

## Contact Points

- **Analysis**: Read `LARSON_CRASH_ROOT_CAUSE_REPORT.md`
- **Implementation**: Follow `LARSON_DIAGNOSTIC_PATCH.md`
- **Quick Ref**: This file
- **Verification**: Run `./verify_race_condition.sh`

---

## Confidence Level

**Root Cause Identification**: 95%+
**C7 Fix Correctness**: 99%+
**Fix Recommendations**: 90%+

---

**Investigation Completed**: 2025-11-22
**Total Investigation Time**: ~2 hours
**Files Analyzed**: 15+
**Lines of Code Reviewed**: ~1,500