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でカバー

効果:

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

サイズテーブル:

static size_t g_class_sizes[7] = {
    2KB, 4KB, 8KB, 16KB, 32KB,    // 標準クラス
    40KB, 52KB                    // Bridge Classes
};

---

⚙️ 環境変数設定

推奨設定:

# 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で無効化

---

🔧 ビルドと使用法

ビルド:

make libhakmem.so     # 共有ライブラリ
make test             # 基本テスト
make bench            # ベンチマーク

使用法:

# 基本的な置換
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時点の最新実装を反映しています。