hakmem/CURRENT_TASK.md

CURRENT TASK (Phase 14–17 Snapshot) – Tiny / Mid / ExternalGuard / Small-Mid

Last Updated: 2025-11-16 Owner: ChatGPT → Phase 17 実装中: Claude Code Size: 約 300 行（Claude 用コンテキスト簡略版）

---

1. 全体の現在地（どこまで終わっているか）

• Tiny (0–1023B)

  • NEW 3-layer front（bump / small_mag / slow）安定。
  • TinyHeapV2: 「alloc フロント＋統計」は実装済みだが、実運用は C2/C3 を UltraHot に委譲。
  • TinyUltraHot（Phase 14）:
    • C2/C3（16B/32B）専用 L0 ultra-fast path（Stealing モデル）。
    • 固定サイズベンチで +16〜36% 改善、hit 率 ≈ 100%。
  • Box 分離（Phase 15）:
    • free ラッパが外部ポインタまで hak_free_at に投げていた問題を修正。
    • BenchMeta（slots など）→ 直接 __libc_free、CoreAlloc（Tiny/Mid）→ hak_free_at の二段構えに整理。

• Mid / PoolTLS（1KB–32KB）

  • PoolTLS Phase 完了（Mid-Large MT ベンチ）
    • ~10.6M ops/s（system malloc より速い構成あり）。
    • lock contention（futex 68%）を lock-free MPSC + bind box で大幅削減。
  • GAP 修正（Tiny 1023B / Mid 1KB〜）:
    • TINY_MAX_SIZE=1023 / MID_MIN_SIZE=1024 で 1KB–8KB の「誰も扱わない帯」は解消済み。

• Shared SuperSlab Pool（Phase 12 – SP-SLOT Box）

  • 1 SuperSlab : 多 class 共有 + SLOT_UNUSED/ACTIVE/EMPTY 追跡。
  • SuperSlab 数: 877 → 72（-92%）、mmap/munmap: -48%、Throughput: +131%。
  • Lock contention P0-5 まで実装済み（Stage 2 lock-free claiming）。

• ExternalGuard（Phase 15）

  • UNKNOWN ポインタ（Tiny/Pool/Mid/L25/registry どこでも捕まらないもの）を最後の箱で扱う。
  • 挙動:
    • hak_super_lookup など全て miss → mincore でページ確認 → 原則「解放せず leak 扱い（安全優先）」。
  • Phase 15 修正で:
    • BenchMeta のポインタを CoreAlloc に渡さなくなり、UNKNOWN 呼び出し回数が激減。
    • mincore の CPU 負荷もベンチではほぼ無視できるレベルまで縮小。

---

2. Tiny 性能の現状（Phase 14–15 時点）

2.1 Fixed-size Tiny ベンチ（HAKMEM vs System）

bench_fixed_size_hakmem / bench_fixed_size_system（workset=128, 500K iterations 相当）

Size	HAKMEM (Phase 15)	System malloc	比率
128B	~16.6M ops/s	~90M ops/s	~18.5%
256B	~16.2M ops/s	~89.6M ops/s	~18.1%
512B	~15.0M ops/s	~90M ops/s	~16.6%
1024B	~15.1M ops/s	~90M ops/s	~16.8%

状態:

• クラッシュは完全解消（workset=64/128 で長尺 500K iter も安定）。
• Tiny UltraHot + 学習層 + ExternalGuard の組み合わせは「正しさ」は OK。
• 性能は system の ~16–18% レベル（約 5–6× 遅い）→ まだ大きな伸びしろあり。

2.2 C2/C3 UltraHot 専用ベンチ

固定サイズ（100K iterations, workset=128）

Size	Baseline (UltraHot OFF)	UltraHot ON	改善率	Hit Rate
16B	~40.4M ops/s	~55.0M	+36.2% 🚀	≈100%
32B	~43.5M ops/s	~50.6M	+16.3% 🚀	≈100%

Random Mixed 256B：

• Baseline: ~8.96M ops/s
• UltraHot ON: ~8.81M ops/s（-1.6%、誤差〜軽微退化）
• 理由: C2/C3 が全体の 1–2% のみ → UltraHot のメリットが平均に薄まる。

結論:

• C2/C3 UltraHot は ターゲットクラスに対しては実用級の Box。
• 他ワークロードでは「ほぼ影響なし（わずかな分岐オーバーヘッドのみ）」の範囲に収まっている。

---

3. Phase 15: ExternalGuard / Domain 分離の成果

3.1 以前の問題

• free ラッパ（core/box/hak_wrappers.inc.h）が:
  • HAKMEM 所有かチェックせず、すべての free(ptr) を hak_free_at(ptr, …) に投げていた。
  • その結果:
    • ベンチ内部 slots（calloc(256, sizeof(void*)) の 2KB など）も CoreAlloc に流入。
    • classify_ptr → UNKNOWN → ExternalGuard → mincore → 「解放せず leak」と判定。
  • ベンチ観測:
    • 約 0.84% の leak（BenchMeta がどんどん漏れる）。
    • mincore が Tiny ベンチ CPU の ~13% を消費。

3.2 修正内容（Phase 15）

• free ラッパ側:
  • 軽量なドメインチェックを追加:
    • Tiny/Pool 用の header magic を安全に読んで、HAKMEM 所有の可能性があるものだけ hak_free_at へ。
    • そうでない（BenchMeta/外部）ポインタは __libc_free へ。
• ExternalGuard:
  • UNKNOWN ポインタを「解放しない（leak）」方針に明示的変更。
  • デバッグ時のみ HAKMEM_EXTERNAL_GUARD_LOG=1 で原因特定用ログを出す。

3.3 結果

• Leak 率:
  • 100K iter: 840 leaks → 0.84%
  • 500K iter: ~4200 leaks → 0.84%
  • ほぼ全部が BenchMeta / 外部ポインタであり、CoreAlloc 側の漏れではないと確認。
• 性能:
  • 256B 固定:
    • Before: 15.9M ops/s
    • After: 16.2M ops/s（+1.9%）→ domain check オーバーヘッドは軽微、むしろ微増。
• 安定性:
  • 全サイズ（128/256/512/1024B）で 500K iter 完走（クラッシュなし）。
  • ExternalGuard 経由の「危ない free」は leak に封じ込められた。

要点:
Box 境界違反（BenchMeta→CoreAlloc 流入）はほぼ完全に解消。
ベンチでの mincore / ExternalGuard コストも許容範囲になった。

---

4. Phase 16: Dynamic Tiny/Mid Boundary A/B Testing（2025-11-16完了）

4.1 実装内容

ENV変数でTiny/Mid境界を動的調整可能にする機能を追加：

• HAKMEM_TINY_MAX_CLASS=7 (デフォルト): Tiny が 0-1023B を担当
• HAKMEM_TINY_MAX_CLASS=5 (実験用): Tiny が 0-255B のみ担当

実装ファイル：

• hakmem_tiny.h/c: tiny_get_max_size() - ENV読取とクラス→サイズマッピング
• hakmem_mid_mt.h/c: mid_get_min_size() - 動的境界調整（サイズギャップ防止）
• hak_alloc_api.inc.h: 静的TINY_MAX_SIZEを動的呼び出しに変更

4.2 A/B Benchmark Results

Size	Config A (C0-C7)	Config B (C0-C5)	変化率
128B	6.34M ops/s	1.38M ops/s	-78% ❌
256B	6.34M ops/s	1.36M ops/s	-79% ❌
512B	5.55M ops/s	1.33M ops/s	-76% ❌
1024B	5.91M ops/s	1.37M ops/s	-77% ❌

4.3 発見と結論

✅ 成功: サイズギャップ修正完了（OOMクラッシュなし） ❌ 失敗: Tiny カバレッジ削減で大幅な性能劣化 (-76% ~ -79%) ⚠️ 根本原因: Mid の粗いサイズクラス (8KB/16KB/32KB) が小サイズで非効率

• Mid は 8KB ページ単位の設計 → 256B-1KB を投げると 8KB ページをほぼ数ブロックのために確保
• ページ fault・TLB・メタデータコストが相対的に巨大
• Tiny は slab + freelist で高密度 → 同じサイズでも桁違いに効率的

教訓（ChatGPT先生分析）:

1. Mid 箱の前提が「8KB〜用」になっている
   • 256B/512B/1024B では 8KB ページをほぼ1〜数個のブロックのために確保 → 非効率
2. パス長も Mid の方が長い（PoolTLS / mid registry / page 管理）
3. 「Tiny を削って Mid に任せれば軽くなる」という仮説は、現行の "8KB〜前提の Mid 設計" では成り立たない

推奨: デフォルト HAKMEM_TINY_MAX_CLASS=7 (C0-C7) を維持

---

5. Phase 17: Small-Mid Allocator Box（256B-4KB専用層）【実装中】

5.1 目標

問題: Tiny C6/C7 (512B/1KB) が 5.5M-5.9M ops/s → system malloc の ~6% レベル 目標: Small-Mid 専用層で 10M-20M ops/s に改善、Tiny/Mid の間のギャップを埋める

5.2 設計原則（ChatGPT先生レビュー済み ✅）

1. 専用SuperSlab分離

   • Small-Mid 専用の SuperSlab プールを用意
   • Tiny の SuperSlab とは完全分離（競合なし）
   • Phase 12 のチャーン問題を回避（最重要！）

2. サイズクラス

   • Small-Mid: 256B / 512B / 1KB / 2KB / 4KB (5 classes)
   • Tiny 側は変更なし（C0-C5 維持）
   • クラス数増加を最小限に抑える

3. 技術流用

   • Header-based fast free (Phase 7 の実績技術)
   • TLS SLL freelist (Tiny と同じ構造)
   • Box理論による明確な境界（一方向依存）

4. 境界設計

   Tiny:      0-255B    (C0-C5, 現在の設計そのまま)
   Small-Mid: 256B-4KB  (新設, 細かいサイズクラス)
   Mid:       8KB-32KB  (既存, ページ単位で効率的)
   

5. ENV制御

   • HAKMEM_SMALLMID_ENABLE=1 で ON/OFF
   • A/B テスト可能（デフォルト OFF）

5.3 実装ステップ

1. Small-Mid 専用ヘッダー作成 (core/hakmem_smallmid.h)

   • 5 size classes 定義
   • TLS freelist 構造
   • Fast alloc/free API

2. 専用 SuperSlab バックエンド (core/hakmem_smallmid_superslab.c)

   • Small-Mid 専用 SuperSlab プール
   • Tiny SuperSlab とは完全分離
   • スパン予約・解放ロジック

3. Fast alloc/free path (core/smallmid_alloc_fast.inc.h)

   • Header-based fast free (Phase 7 流用)
   • TLS SLL pop/push (Tiny と同じ)
   • Bump allocation fallback

4. ルーティング統合 (hak_alloc_api.inc.h)

   if (size <= 255)          → Tiny
   else if (size <= 4096)    → Small-Mid  // NEW!
   else if (size <= 32768)   → Mid
   else                      → ACE / mmap
   

5. A/B ベンチマーク

   • Config A: Small-Mid OFF (現状)
   • Config B: Small-Mid ON (新実装)
   • 256B / 512B / 1KB / 2KB / 4KB で比較

5.4 懸念点と対策（ChatGPT先生指摘）

❌ 懸念1: SuperSlab 共有の競合

• 対策: Small-Mid が「自分専用のスパン」を予約して、その中だけで完結する境界設計

❌ 懸念2: クラス数の増加

• 対策: Tiny 側のクラスは増やさない（C0-C5 そのまま）、Small-Mid は 5 クラスに抑える

❌ 懸念3: メタデータオーバーヘッド

• 対策: TLS state + サイズクラス配列のみ（数KB程度）、影響は最小限

5.5 期待される効果

• 性能改善: 256B-1KB で 5.5M → 10-20M ops/s (目標 2-4倍)
• ギャップ解消: Tiny (6M) と Mid (?) の間を埋める
• Box 理論的健全性: 境界明確、一方向依存、A/B 可能

5.6 実装状況

🚧 IN PROGRESS - 設計方針確定、実装開始準備中

---

6. 未達成の目標・残課題（次フェーズ候補）

6.1 Tiny 性能ギャップ（System の ~18% 止まり）

現状:

• System malloc が ~90M ops/s レベルのところ、
• HAKMEM は 128〜1024B 固定で ~15–16M ops/s（約 18%）。

原因の切り分け（これまでの調査から）:

• Front（UltraHot/TinyHeapV2/TLS SLL）のパス長はかなり短縮済み。
• L1 dcache miss / instructions / branches は Phase 14 で大幅削減済みだが、
  • まだ Tiny が 0–1023B を全部抱えており、
  • 特に 512/1024B が Superslab/Pool 側のメタ負荷に効いている可能性。

候補:

• Phase 17 で実装中！ Small-Mid Box（256B〜4KB 専用箱）を設計し、Tiny/Mid の間を分離する。
  • 詳細は § 5. Phase 17 を参照

6.2 UltraHot/TinyHeapV2 の拡張 or 整理

• C2/C3 UltraHot は成功（16/32B 用）。
• C4/C5 まで拡張した試み（Phase 14-B）は:
  • Fixed-size では改善あり。
  • Random Mixed で shared_pool_acquire_slab() が 47.5% まで膨らみ、大退化。
  • 原因: Superslab/TLS 在庫のバランスを壊す「窃取カスケード」。

方針:

• UltraHot は C2/C3 専用 Box に戻す（C4/C5 は一旦対象外にする）。
• もし C4/C5 を最適化したいなら、SmallMid Box の中で別設計する。

6.3 ExternalGuard の統計と自動アラート

• 現在:
  • HAKMEM_EXTERNAL_GUARD_STATS=1 で統計を手動出力。
  • 100+ 回呼ばれたら WARNING を出すのみ。
• 構想:
  • 「ExternalGuard 呼び出しが一定閾値を超えたら、自動で簡易レポートを吐く」Box を追加。
  • 例: Top N 呼び出し元アドレス、サイズ帯、mincore 結果 など。

---

7. Claude Code 君向け TODO（Phase 17 実装リスト）

7.1 Phase 17: Small-Mid Box 実装 🚧

1. ヘッダー作成 (core/hakmem_smallmid.h)

   • 5 size classes 定義 (256B/512B/1KB/2KB/4KB)
   • TLS freelist 構造体定義
   • size → class マッピング関数
   • Fast alloc/free API 宣言

2. 専用 SuperSlab バックエンド (core/hakmem_smallmid_superslab.c)

   • Small-Mid 専用 SuperSlab プール（Tiny と完全分離）
   • スパン予約・解放ロジック
   • refill 関数

3. Fast alloc/free 実装 (core/smallmid_alloc_fast.inc.h, core/hakmem_smallmid.c)

   • Header-based fast free (Phase 7 技術流用)
   • TLS SLL pop/push (Tiny と同じ構造)
   • Bump allocation fallback
   • ENV 制御: HAKMEM_SMALLMID_ENABLE=1

4. ルーティング統合 (hak_alloc_api.inc.h)

   • Small-Mid 層の追加（256B-4KB）
   • ENV で ON/OFF 切り替え

5. A/B ベンチマーク

   • Config A: Small-Mid OFF（現状）
   • Config B: Small-Mid ON（新実装）
   • 256B/512B/1KB/2KB/4KB で性能測定

6. ドキュメント作成

   • PHASE17_SMALLMID_BOX_DESIGN.md - 設計書
   • PHASE17_SMALLMID_AB_RESULTS.md - A/B テスト結果

7.2 その他タスク（Phase 17 後）

1. Phase 16 結果の詳細分析

   • ✅ 完了 - CURRENT_TASK.md に記録済み

2. C2/C3 UltraHot のコード掃除

   • C4/C5 関連の定義・分岐を ENV ガードか別 Box に切り出し
   • デフォルト構成では C2/C3 だけを対象とする形に簡素化

3. ExternalGuard 統計の自動化

   • 閾値超過時の自動レポート機能

この CURRENT_TASK.md は、あくまで「Phase 14–17 周辺の簡略版メモ」です。 より過去の詳細な経緯は CURRENT_TASK_FULL.md や各 PHASE レポートを参照してください。

---

8. Phase 17 実装ログ（進行中）

2025-11-16

• ✅ Phase 16 完了・A/B テスト結果分析
• ✅ ChatGPT 先生の Small-Mid Box 提案レビュー
• ✅ CURRENT_TASK.md 更新（Phase 17 設計方針確定）
• 🚧 次: core/hakmem_smallmid.h ヘッダー作成開始