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つのドキュメントを確認

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: 現状ベースラインを記録

# 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 の計画を立てる

# 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 エラーが出た場合

# 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 を参照

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

# 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 を特定して最適化

テストが失敗した場合

# 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 を更新

---

次のステップ

# 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! ✨