hakmem/docs/design/REFACTOR_QUICK_START.md

# HAKMEM Tiny リファクタリング - クイックスタートガイド

## 本ドキュメントについて

3つの計画書を読む時間がない場合、このガイドで必要な情報をすべて把握できます。

---

## 1分で理解

**目標**: hakmem_tiny_free.inc (1470行) を 500行以下に分割

**効果**:
- Fast path: 20+ instructions → 3-4 instructions (-80%)
- Throughput: +10-25%
- Code review: 3h → 30min (-90%)

**期間**: 6週間 (20時間コーディング)

---

## 5分で理解

### 現状の問題

```
hakmem_tiny_free.inc (1470行)
├─ Free パス (400行)
├─ SuperSlab Alloc (400行)
├─ SuperSlab Free (400行)
├─ Query (commented-out, 100行)
└─ Shutdown (30行)

問題: 単一ファイルに4つの責務が混在
→ 複雑度が高い, バグが多発, 保守が困難
```

### 解決策

```
9つのBoxに分割 (各500行以下):

Box 1: tiny_atomic.h (80行) - Atomic ops
Box 2: tiny_remote_queue.inc.h (300行) - Remote queue
Box 3: hakmem_tiny_superslab.{c,h} (810行, 既存)
Box 4: tiny_adopt.inc.h (300行) - Adopt logic
Box 5: tiny_alloc_fast.inc.h (250行) - Fast path (3-4 cmd)
Box 6: tiny_free_fast.inc.h (200行) - Same-thread free
Box 7: Statistics & Query (existing)
Box 8: Lifecycle & Init (split into 5 files)
Box 9: Intel-specific (split into 3 files)

各Boxが単一責務 → テスト可能 → 保守しやすい
```

---

## 15分で全体理解

### 実装計画 (6週間)

| Week | Focus | Files | Lines |
|------|-------|-------|-------|
| 1 | Fast Path | tiny_atomic.h, tiny_alloc_fast.inc.h, tiny_free_fast.inc.h | 530 |
| 2 | Remote/Own | tiny_remote_queue.inc.h, tiny_owner.inc.h | 420 |
| 3 | Publish/Adopt | tiny_adopt.inc.h, mailbox split | 430 |
| 4 | Alloc/Free Slow | tiny_alloc_slow.inc.h, tiny_free_remote.inc.h, tiny_free_guard.inc.h | 720 |
| 5 | Lifecycle/Intel | tiny_init_*.inc.h, tiny_lifecycle_*.inc.h, tiny_intel_*.inc.h | 1070 |
| 6 | Test/Bench | Unit tests, Integration tests, Performance validation | - |

### 期待効果

| Metric | Before | After | Improvement |
|--------|--------|-------|-------------|
| Fast path cmd | 20+ | 3-4 | -80% |
| Max file size | 1470行 | 500行 | -66% |
| Code review | 3h | 30min | -90% |
| Throughput | 52 M/s | 58-65 M/s | +10-25% |

---

## 30分で準備完了

### Step 1: 3つのドキュメントを確認

```bash
ls -lh REFACTOR_*.md

# 1. REFACTOR_SUMMARY.md (13KB) を読む (15分)
# 2. REFACTOR_PLAN.md (22KB) で詳細確認 (30分)
# 3. REFACTOR_IMPLEMENTATION_GUIDE.md (17KB) で実装例確認 (20分)
```

### Step 2: 現状ベースラインを記録

```bash
# Fast path latency を測定
./larson_hakmem 16 1 1000 1000 0 > baseline.txt

# Assembly を確認
gcc -S -O3 core/hakmem_tiny.c

# Include 依存関係を可視化
cd core && \
grep -h "^#include" *.c *.h | sort | uniq | wc -l
# Expected: 100+ includes
```

### Step 3: Week 1 の計画を立てる

```bash
# REFACTOR_IMPLEMENTATION_GUIDE.md Phase 1.1-1.4 をプリントアウト
wc -l core/tiny_atomic.h core/tiny_alloc_fast.inc.h core/tiny_free_fast.inc.h
# Expected: 80 + 250 + 200 = 530行

# テストテンプレートを確認
# REFACTOR_IMPLEMENTATION_GUIDE.md の Testing Framework セクション
```

---

## よくある質問

### Q1: 実装の優先順位は?

**A**: 箱理論に基づく依存関係順:
1. **Box 1 (tiny_atomic.h)** - 最下層、他すべてが依存
2. **Box 2 (Remote/Ownership)** - リモート通信の基盤
3. **Box 3 (SuperSlab)** - 中核アロケータ (既存)
4. **Box 4 (Publish/Adopt)** - マルチスレッド連携
5. **Box 5-6 (Alloc/Free)** - メインパス
6. **Box 7-9** - 周辺・最適化

詳細: REFACTOR_PLAN.md Phase 3

---

### Q2: パフォーマンス回帰のリスクは?

**A**: 4段階の検証で排除:
1. **Assembly review** - 命令数を確認 (Week 1)
2. **Unit tests** - Box ごとのテスト (Week 1-5)
3. **Integration tests** - End-to-end テスト (Week 5-6)
4. **Larson benchmark** - 全体パフォーマンス (Week 6)

詳細: REFACTOR_IMPLEMENTATION_GUIDE.md の Performance Validation

---

### Q3: 既存コードとの互換性は?

**A**: 完全に保つ:
- 古い .inc ファイルは削除しない
- Feature flags で新旧を切り替え可能 (HAKMEM_TINY_NEW_FAST_PATH=0)
- Rollback plan が完備されている

詳細: REFACTOR_IMPLEMENTATION_GUIDE.md の Rollback Plan

---

### Q4: 循環依存はどう防ぐ?

**A**: 層状の DAG (Directed Acyclic Graph) 設計:

```
Layer 0 (tiny_atomic.h)
    ↓
Layer 1 (tiny_remote_queue.inc.h)
    ↓
Layer 2-3 (SuperSlab, Publish/Adopt)
    ↓
Layer 4-6 (Alloc/Free)
    ↓
Layer 7-9 (Stats, Lifecycle, Intel)

各層は上位層にのみ依存 → 循環依存なし
```

詳細: REFACTOR_PLAN.md Phase 5

---

### Q5: テストはどこまで書く?

**A**: 3段階:

| Level | Coverage | Time |
|-------|----------|------|
| Unit | 個々の関数テスト | 30min/func |
| Integration | パス全体テスト | 1h/path |
| Performance | Larson benchmark | 2h |

例: REFACTOR_IMPLEMENTATION_GUIDE.md の Testing Framework

---

## 実装チェックリスト (印刷向け)

### Week 1: Fast Path

```
□ tiny_atomic.h を作成
  □ macros: load, store, cas, exchange
  □ unit tests を書く
  □ コンパイル確認

□ tiny_alloc_fast.inc.h を作成
  □ tiny_alloc_fast_pop() (3-4 cmd)
  □ tiny_alloc_fast_push()
  □ unit tests
  □ Cache hit rate を測定

□ tiny_free_fast.inc.h を作成
  □ tiny_free_fast() (ownership check)
  □ Same-thread free パス
  □ unit tests

□ hakmem_tiny_free.inc を refactor
  □ Fast path を抽出 (1470 → 800行)
  □ コンパイル確認
  □ Integration tests 実行
  □ Larson benchmark で +10% を目指す
```

### Week 2-6: その他の Box

- REFACTOR_PLAN.md Phase 3 を参照
- REFACTOR_IMPLEMENTATION_GUIDE.md で各 Box の実装例を確認
- 毎週 Benchmark を実行して進捗を記録

---

## デバッグのコツ

### Include order エラーが出た場合

```bash
# Include の依存関係を確認
grep "^#include" core/tiny_*.h | grep -v "<" | head -20

# Compilation order を確認
gcc -c -E core/hakmem_tiny.c 2>&1 | grep -A5 "error:"

# 解決策: REFACTOR_PLAN.md Phase 5 の include order を参照
```

### パフォーマンスが低下した場合

```bash
# Assembly を確認
gcc -S -O3 core/hakmem_tiny.c
grep -A10 "tiny_alloc_fast_pop:" core/hakmem_tiny.s | wc -l
# Expected: <= 8 instructions

# Profiling
perf record -g ./larson_hakmem 16 1 1000 1000 0
perf report

# Hot spot を特定して最適化
```

### テストが失敗した場合

```bash
# Unit test を詳細表示
./test_tiny_atomic -v

# 特定の Box をテスト
gcc -I./core tests/test_tiny_atomic.c -lhakmem -o /tmp/test
/tmp/test

# 既知の問題がないか REFACTOR_PLAN.md Phase 7 (Risk) を確認
```

---

## 重要なリマインダー

1. **Baseline を記録**: Week 1 開始前に必ず larson benchmark を実行
2. **毎週ベンチマーク**: パフォーマンス回帰を早期発見
3. **テスト優先**: コード量より テストカバレッジを重視
4. **Rollback plan**: 必ず理解して実装開始
5. **ドキュメント更新**: 各 Box 完成時に doc を更新

---

## 次のステップ

```bash
# Step 1: REFACTOR_SUMMARY.md を読む
less REFACTOR_SUMMARY.md

# Step 2: REFACTOR_PLAN.md で詳細確認
less REFACTOR_PLAN.md

# Step 3: Baseline ベンチマークを実行
make clean && make
./larson_hakmem 16 1 1000 1000 0 > baseline.txt

# Step 4: Week 1 の実装を開始
cd core
# ... tiny_atomic.h を作成
```

---

## 連絡先・質問

- **戦略/分析**: REFACTOR_PLAN.md
- **実装例**: REFACTOR_IMPLEMENTATION_GUIDE.md
- **期待効果**: REFACTOR_SUMMARY.md

✨ **Happy Refactoring!** ✨