hakmem/docs/design/CURRENT_ARCHITECTURE.md

# hakmem Current Architecture - 現在実装仕様

**最終更新**: 2025-10-26  
**バージョン**: Phase 6.21 (STABLE)  
**廃止機能**: DYN1/DYN2 - Phase 6.21で無効化済み

---

## 🏗️ 3階層アーキテクチャ (SACS-3: Size-Only Allocation)

```
┌─ L0 Tiny (≤1KB) ──────────────── TLS Magnum ──┐
│ 8固定クラス + TLS Active Slab + MPSC Queue      │
├─ L1 ACE (1KB-2MB) ───── 7固定クラス ────────┤ ← Bridge Classes!
│ 2/4/8/16/32/40/52KB                                 │
└─ L2 Big (≥2MB) ─────────── BigCache + mmap ─────┘
```

---

## 📊 詳細仕様

### **L0 Tiny Pool (≤1KB)**
- **サイズクラス**: 8B, 16B, 32B, 64B, 128B, 256B, 512B, 1KB (8クラス固定)
- **特徴**:
  - TLS Magazine: 高速LIFOキャッシュ
  - TLS Active Slab: 所有スレッドのみbitmap更新（ロックレス）
  - MPSC remote-free: 他スレッドのfreeを効率処理
- **用途**: ベンチマーク勝利の核心技術

### **L1 ACE Layer (1KB-2MB)**
- **Mid Pool**: 2KB, 4KB, 8KB, 16KB, 32KB （5クラス）
- **Bridge Classes**: 40KB, 52KB （★Phase 6.21で追加）
- **Large Pool**: 64KB, 128KB, 256KB, 512KB, 1MB （5クラス）
- **合計**: 7固定クラス （DYN1/DYN2は廃止）
- **W_MAX丸め**: `size × 1.30` まで上位クラス許可

### **L2 Big Layer (≥2MB)**
- **技術**: BigCache + mmap 
- **しきい値**: 2MB（THP境界）
- **特徴**: バッチmadviseで最適化

---

## 🎯 Bridge Classes (Phase 6.21追加)

### **問題解決**:
- **従来**: 32KB → 64KB間に30KBギャップ
- **Bridge追加**: 40KB, 52KBでカバー

### **効果**:
```c
// Bridge効果
35KBリクエスト → 40KB (1.14倍) ← 従来はfallback
40KBリクエスト → 40KB (1.00倍) ← 従来は64KB (1.60倍)
50KBリクエスト → 52KB (1.04倍) ← 従来は64KB (1.28倍)
```

### **サイズテーブル**:
```c
static size_t g_class_sizes[7] = {
    2KB, 4KB, 8KB, 16KB, 32KB,    // 標準クラス
    40KB, 52KB                    // Bridge Classes
};
```

---

## ⚙️ 環境変数設定

### **推奨設定**:
```bash
# 5つの簡単モード (Phase 6.8+)
export HAKMEM_MODE=minimal    # ベースライン（全機能OFF）
export HAKMEM_MODE=balanced   # 推奨（BigCache + FROZEN）
export HAKMEM_MODE=fast       # 本番用（TLS最適化）
export HAKMEM_MODE=learning   # 開発用（学習ON）
export HAKMEM_MODE=research   # デバッグ用（全機能ON）
```

### **重要変更**:
- ✅ **学習機能**: ほぼ無効化（DYN1/DYN2削除）
- ✅ **Call-siteプロファイリング**: 単純サイズ分類に
- ✅ **UCB1/ELO学習**: 非機能化

---

## 📈 ベンチマーク結果

### **16B-64KB 勝利の理由**:
| テスト | HAKMEM | mimalloc | 勝敗 | 原因 |
|--------|--------|----------|------|------|
| 16B LIFO | 145.53M | 144.39M | ✅ HAKMEM | TLS Active Slab |
| 16B FIFO | 154.15M | 172.94M | ❌ mimalloc | +12% |
| 16B インターリーブ | 176.05M | 164.68M | ✅ HAKMEM | MPSC効率 |
| 64B LIFO | 94.38M | 91.42M | ✅ HAKMEM | TLSスラブ |
| 混合サイズ | 163.76M | 152.27M | ✅ HAKMEM | Bridge効果 |

### **勝利の技術的理由**:
- **Tiny Pool**: TLS Active Slabがスレッド競合を排除
- **Bridge Classes**: 32-64KBギャップを解消
- **SACS-3**: 複雑さを削減し安定性向上

---

## 📁 主要ソースファイル

### **現行活性ファイル**:
```
hakmem.c              - メインアロケーター
hakmem_tiny.c/h       - L0 Tiny Pool
hakmem_pool.c/h       - L1 Mid Pool (2-32KB)
hakmem_l25_pool.c/h   - L1 Large Pool (64KB-1MB)  
hakmem_bigcache.c/h   - L2 Big Cache
hakmem_policy.c/h     - 設定とBridge Classes
hakmem_config.c/h     - モード管理
hakmem_ace.c/h        - L1統合レイヤー
```

### **非活性ファイル（学習関連）**:
```
hakmem_*.c - *_learner*, *_elo*, *_evo*  - Phase 6.21で無効化
```

---

## 🔧 ビルドと使用法

### **ビルド**:
```bash
make libhakmem.so     # 共有ライブラリ
make test             # 基本テスト
make bench            # ベンチマーク
```

### **使用法**:
```bash
# 基本的な置換
LD_PRELOAD=./libhakmem.so program

# モード選択
HAKMEM_MODE=balanced LD_PRELOAD=./libhakmem.so program

# テスト
./test_bridge         # Bridge Classes動作確認
./test_scaling        # スケーラビリティテスト
```

---

## 🎓 設計思想

### **単純化の教訓**:
1. **動的 > 固定**: DYN1/DYN2失敗 → Bridge Classes成功
2. **複雑 > 単純**: Call-site学習失敗 → SACS-3成功
3. **過適合 > 現実解**: 完璧さより実用性

### **技術的貢献**:
- **Bridge Classes**: ギャップ解消のエレガントな解決策
- **TLS Active Slab**: スレッド競合の最小化
- **SACS-3**: サイズ専用3階層の安定性

---

## 🎯 結論

hakmemは**「複雑な学習アプローチから単純な固定アプローチへ」**の進化を遂げ、
既存技術（mimalloc）と競合可能なレベルに達しました。

**強み**: シンプルさ、安定性、TLS最適化
**弱み**: 大サイズ（>2MB）での性能差
**今後**: TLSリング拡大やmmap最適化の余地あり

---

**最終確認**: このドキュメントはPhase 6.21時点の最新実装を反映しています。