hakmem/docs/analysis/REFACTOR_SUMMARY.md

# HAKMEM Tiny Allocator リファクタリング計画 - エグゼクティブサマリー

## 概要

HAKMEM Tiny allocator の **箱理論に基づくスーパーリファクタリング計画** です。

**目標**: 1470行の mega-file (hakmem_tiny_free.inc) を、500行以下の責務単位に分割し、保守性・性能・開発速度を向上させる。

---

## 現状分析

### 問題点

| 項目 | 現状 | 問題 |
|------|------|------|
| **最大ファイル** | hakmem_tiny_free.inc (1470行) | 複雑度 高、バグ多発 |
| **責務の混在** | Free + Alloc + Query + Shutdown | 単一責務原則(SRP)違反 |
| **Include の複雑性** | hakmem_tiny.c が44個の .inc を include | 依存関係が不明確 |
| **パフォーマンス** | Fast path で20+命令 | System tcache の3-4命令に劣る |
| **保守性** | 3時間 /コードレビュー | 複雑度が高い |

### 目指すべき姿

| 項目 | 現状 | 目標 | 効果 |
|------|------|------|------|
| **最大ファイル** | 1470行 | <= 500行 | -66% 複雑度 |
| **責務分離** | 混在 | 9つの Box | 100% 明確化 |
| **Fast path** | 20+命令 | 3-4命令 | -80% cycles |
| **コードレビュー** | 3時間 | 30分 | -90% 時間 |
| **Throughput** | 52 M ops/s | 58-65 M ops/s | +10-25% |

---

## 箱理論に基づく 9つの Box

```
┌─────────────────────────────────────────────────────────────┐
│                    Integration Layer                        │
│              (hakmem_tiny.c - include aggregator)           │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│ Box 9: Intel-specific optimizations (3 files × 300行)      │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│ Box 8: Lifecycle & Init (5 files × 150行)                  │
├─────────────────────────────────────────────────────────────┤
│ Box 7: Statistics & Query (4 files × 200行, existing)      │
├─────────────────────────────────────────────────────────────┤
│ Box 6: Free Path (3 files × 250行)                         │
│   - tiny_free_fast.inc.h (same-thread)                     │
│   - tiny_free_remote.inc.h (cross-thread)                  │
│   - tiny_free_guard.inc.h (validation)                     │
├─────────────────────────────────────────────────────────────┤
│ Box 5: Allocation Path (3 files × 350行)                   │
│   - tiny_alloc_fast.inc.h (cache pop, 3-4 cmd)            │
│   - hakmem_tiny_refill.inc.h (existing, 410行)            │
│   - tiny_alloc_slow.inc.h (superslab refill)               │
├─────────────────────────────────────────────────────────────┤
│ Box 4: Publish/Adopt (4 files × 300行)                     │
│   - tiny_publish.c (existing)                               │
│   - tiny_mailbox.c (existing + split)                       │
│   - tiny_adopt.inc.h (new)                                  │
├─────────────────────────────────────────────────────────────┤
│ Box 3: SuperSlab Core (2 files × 800行)                    │
│   - hakmem_tiny_superslab.h/c (existing, well-structured)  │
├─────────────────────────────────────────────────────────────┤
│ Box 2: Remote Queue & Ownership (4 files × 350行)          │
│   - tiny_remote_queue.inc.h (new)                           │
│   - tiny_remote_drain.inc.h (new)                           │
│   - tiny_owner.inc.h (new)                                  │
│   - slab_handle.h (existing, 295行)                         │
├─────────────────────────────────────────────────────────────┤
│ Box 1: Atomic Ops (1 file × 80行)                          │
│   - tiny_atomic.h (new)                                     │
└─────────────────────────────────────────────────────────────┘
```

---

## 実装計画 (6週間)

### Week 1: Fast Path (Priority 1) ✨
**目標**: 3-4命令のFast pathを実現

**成果物**:
- [ ] `tiny_atomic.h` (80行) - Atomic操作の統一インターフェース
- [ ] `tiny_alloc_fast.inc.h` (250行) - TLS cache pop (3-4 cmd)
- [ ] `tiny_free_fast.inc.h` (200行) - Same-thread free
- [ ] hakmem_tiny_free.inc 削減 (1470行 → 800行)

**期待値**:
- Fast path: 3-4 instructions (assembly review)
- Throughput: +10% (16-64B size classes)

---

### Week 2: Remote & Ownership (Priority 2)
**目標**: Remote queue と owner TID 管理をモジュール化

**成果物**:
- [ ] `tiny_remote_queue.inc.h` (300行) - MPSC stack ops
- [ ] `tiny_remote_drain.inc.h` (150行) - Drain logic
- [ ] `tiny_owner.inc.h` (120行) - Ownership tracking
- [ ] tiny_remote.c 整理 (645行 → 350行)

**期待値**:
- Remote queue ops を分離・テスト可能に
- Cross-thread free の安定性向上

---

### Week 3: SuperSlab Integration (Priority 3)
**目標**: Publish/Adopt メカニズムを統合

**成果物**:
- [ ] `tiny_adopt.inc.h` (300行) - Adopt logic
- [ ] `tiny_mailbox_push.inc.h` (80行)
- [ ] `tiny_mailbox_drain.inc.h` (150行)
- [ ] Box 3 (SuperSlab) 強化

**期待値**:
- Multi-thread adoption が完全に統合
- Memory efficiency向上

---

### Week 4: Allocation/Free Slow Path (Priority 4)
**目標**: Slow pathを明確に分離

**成果物**:
- [ ] `tiny_alloc_slow.inc.h` (300行) - SuperSlab refill
- [ ] `tiny_free_remote.inc.h` (300行) - Cross-thread push
- [ ] `tiny_free_guard.inc.h` (120行) - Validation
- [ ] hakmem_tiny_free.inc (1470行 → 300行に最終化)

**期待値**:
- Slow path を20+ 関数に分割・テスト可能に
- Guard check の安定性確保

---

### Week 5: Lifecycle & Config (Priority 5)
**目標**: 初期化・クリーンアップを統一化

**成果物**:
- [ ] `tiny_init_globals.inc.h` (150行)
- [ ] `tiny_init_config.inc.h` (150行)
- [ ] `tiny_init_pools.inc.h` (150行)
- [ ] `tiny_lifecycle_trim.inc.h` (120行)
- [ ] `tiny_lifecycle_shutdown.inc.h` (120行)

**期待値**:
- hakmem_tiny_init.inc (544行 → 150行 × 3に分割)
- 重複を排除、設定管理を統一化

---

### Week 6: Testing + Integration + Benchmark
**目標**: 完全なテスト・ベンチマーク・ドキュメント完備

**成果物**:
- [ ] Unit tests (per Box, 10+テスト)
- [ ] Integration tests (end-to-end)
- [ ] Performance validation
- [ ] Documentation update

**期待値**:
- 全テスト PASS
- Throughput: +10-25% (16-64B size classes)
- Memory efficiency: System 並以上

---

## 分割戦略 (詳細)

### 抽出元ファイル

| From | To | Lines | Notes |
|------|----|----|------|
| hakmem_tiny_free.inc | tiny_alloc_fast.inc.h | 150 | Fast pop/push |
| hakmem_tiny_free.inc | tiny_free_fast.inc.h | 200 | Same-thread free |
| hakmem_tiny_free.inc | tiny_remote_queue.inc.h | 300 | Remote queue ops |
| hakmem_tiny_free.inc | tiny_alloc_slow.inc.h | 300 | SuperSlab refill |
| hakmem_tiny_free.inc | tiny_free_remote.inc.h | 300 | Cross-thread push |
| hakmem_tiny_free.inc | tiny_free_guard.inc.h | 120 | Validation |
| hakmem_tiny_free.inc | tiny_lifecycle_shutdown.inc.h | 30 | Cleanup |
| hakmem_tiny_free.inc | **削除** | 100 | Commented Query API |
| **Total extract** | - | **1100行** | **-75%削減** |
| **Remaining** | - | **370行** | **Glue code** |

### 新規ファイル一覧

```
✨ New Files (9個, 合計 ~2500行):

Box 1:
  - tiny_atomic.h (80行)

Box 2:
  - tiny_remote_queue.inc.h (300行)
  - tiny_remote_drain.inc.h (150行)
  - tiny_owner.inc.h (120行)

Box 4:
  - tiny_adopt.inc.h (300行)
  - tiny_mailbox_push.inc.h (80行)
  - tiny_mailbox_drain.inc.h (150行)

Box 5:
  - tiny_alloc_fast.inc.h (250行)
  - tiny_alloc_slow.inc.h (300行)

Box 6:
  - tiny_free_fast.inc.h (200行)
  - tiny_free_remote.inc.h (300行)
  - tiny_free_guard.inc.h (120行)

Box 8:
  - tiny_init_globals.inc.h (150行)
  - tiny_init_config.inc.h (150行)
  - tiny_init_pools.inc.h (150行)
  - tiny_lifecycle_trim.inc.h (120行)
  - tiny_lifecycle_shutdown.inc.h (120行)

Box 9:
  - tiny_intel_common.inc.h (150行)
  - tiny_intel_fast.inc.h (300行)
  - tiny_intel_cache.inc.h (200行)
```

---

## 期待される効果

### パフォーマンス

| Metric | Before | After | Improvement |
|--------|--------|-------|-------------|
| Fast path instruction count | 20+ | 3-4 | -80% |
| Fast path cycle latency | 50-100 | 15-20 | -70% |
| Branch misprediction penalty | High | Low | -60% |
| Tiny (16-64B) throughput | 52 M ops/s | 58-65 M ops/s | +10-25% |
| Cache hit rate | 70% | 85%+ | +15% |

### 保守性

| Metric | Before | After |
|--------|--------|-------|
| Max file size | 1470行 | 500行以下 |
| Cyclic dependencies | 多数 | 0 (完全DAG) |
| Code review time | 3h | 30min |
| Test coverage | ~60% | 95%+ |
| SRP compliance | 30% | 100% |

### 開発速度

| Task | Before | After |
|------|--------|-------|
| Bug fix | 2-4h | 30min |
| Optimization | 4-6h | 1-2h |
| Feature add | 6-8h | 2-3h |
| Regression debug | 2-3h | 30min |

---

## Include 順序 (新規)

**hakmem_tiny.c** の新規フォーマット:

```
LAYER 0: tiny_atomic.h
LAYER 1: tiny_owner.inc.h, slab_handle.h
LAYER 2: hakmem_tiny_superslab.{h,c}
LAYER 2b: tiny_remote_queue.inc.h, tiny_remote_drain.inc.h
LAYER 3: tiny_publish.{h,c}, tiny_mailbox.*, tiny_adopt.inc.h
LAYER 4: tiny_alloc_fast.inc.h, tiny_free_fast.inc.h
LAYER 5: hakmem_tiny_refill.inc.h, tiny_alloc_slow.inc.h, tiny_free_remote.inc.h, tiny_free_guard.inc.h
LAYER 6: hakmem_tiny_stats.*, hakmem_tiny_query.c
LAYER 7: tiny_init_*.inc.h, tiny_lifecycle_*.inc.h
LAYER 8: tiny_intel_*.inc.h
LAYER 9: Legacy compat (.inc files)
```

**依存関係の完全DAG**:
```
L0 (tiny_atomic.h)
  ↓
L1 (tiny_owner, slab_handle)
  ↓
L2 (SuperSlab, remote_queue, remote_drain)
  ↓
L3 (Publish/Adopt)
  ↓
L4 (Fast path)
  ↓
L5 (Slow path)
  ↓
L6-L9 (Stats, Lifecycle, Intel, Legacy)
```

---

## Risk & Mitigation

| Risk | Impact | Mitigation |
|------|--------|-----------|
| Include order bug | Compilation fail | Layer-wise testing, CI |
| Inlining threshold | Performance regression | `__always_inline`, perf profiling |
| TLS contention | Bottleneck | Lock-free CAS, batch ops |
| Remote queue scalability | High-contention bottleneck | Adaptive backoff, sharding |

---

## Success Criteria

✅ **All tests pass** (unit + integration + larson)
✅ **Fast path = 3-4 instruction** (assembly verification)
✅ **+10-25% throughput** (16-64B size classes, vs baseline)
✅ **All files <= 500行**
✅ **Zero cyclic dependencies** (include graph analysis)
✅ **Documentation complete**

---

## ドキュメント

このリファクタリング計画は以下で構成:

1. **REFACTOR_PLAN.md** - 詳細な戦略・分析・タイムライン
2. **REFACTOR_IMPLEMENTATION_GUIDE.md** - 実装手順・コード例・テスト
3. **REFACTOR_SUMMARY.md** (このファイル) - エグゼクティブサマリー

---

## Next Steps

1. **Week 1 を開始**: Box 1 (tiny_atomic.h) を作成
2. **Benchmark を測定**: Baseline を記録
3. **CI を強化**: Include order を自動チェック
4. **Gradual migration**: Box ごとに段階的に進行

---

## 連絡先・質問

- 詳細な実装は REFACTOR_IMPLEMENTATION_GUIDE.md を参照
- 全体戦略は REFACTOR_PLAN.md を参照
- 各 Box の責務は Phase 2 セクションを参照

✨ **Let's refactor HAKMEM Tiny to be as simple and fast as System tcache!** ✨