## HAKMEM 状況メモ (2025-12-05 更新)

### 現在の状態（Tiny / Superslab / Warm Pool）
- Tiny Front / Superslab / Shared Pool は Box Theory 準拠で 3 層構造に整理済み（HOT/WARM/COLD）。
- Tiny Gatekeeper Box（alloc/free）と Tiny Route Box により、USER→BASE 変換と Tiny vs Pool のルーティングを入口 1 箇所に集約。
- Superslab Tier Box（HOT/DRAINING/FREE）＋ Release Guard Box により、SuperSlab ライフサイクルと eager FREE の安全な境界を定義。
- Warm Pool 層:
  - `tiny_warm_pool.h`: per-thread の HOT SuperSlab プール。
  - `warm_pool_stats_box.h`: hits/misses/prefilled の統計箱。
  - `warm_pool_prefill_box.h`: registry スキャン時に Warm Pool を事前充填する cold-path helper。
- Prefault Box（`ss_prefault_box.h`）は追加済みだが、4MB MAP_POPULATE 問題を避けるためデフォルト OFF（`HAKMEM_SS_PREFAULT=0`）に設定。

### 直近の成果
- Gatekeeper inlining（Phase A-1）完了：`malloc`/`free` ラッパの関数呼び出しを削減しつつ、Box 境界は維持。
- Unified Cache Refill の debug 検証を 1 箇所に集約し、リリースビルドの HOT パスを軽量化：
  - `bench_random_mixed_hakmem 1000000 256 42` が約 4.3M → 5.0M ops/s（~+17%）に改善。
- Tiny-only/Tiny Mixed / Non-Tiny の条件差分をドキュメント化・分離：
  - `bench_random_mixed_hakmem` に `HAKMEM_BENCH_MIN_SIZE` / `HAKMEM_BENCH_MAX_SIZE` を追加し、
    - 8–128B（Tiny-only）
    - 129–1024B（Tiny C5–C7 専用）
    を個別に測定可能にした。
  - `docs/PERF_ANALYSIS_TINY_MIXED.md` ほかに、8–128B/200K/ws=400（旧 Tiny 専用）と現在の 16–1024B/1M/ws=256（Tiny+Non-Tiny 混在）の違いを明記。
- Unified Cache Refill 安全化（Step 1 完了）:
  - `core/front/tiny_unified_cache.c` の `unified_cache_refill()` で `max_batch <= 256` を保証し、`out[256]` と常に整合するよう修正。
  - C5〜C7 の Unified Cache 容量・バッチサイズを増やす実験を行ってもスタック破壊が起きない状態にした。
- Tiny Page Box（C7 Tiny-Plus 層）の導入（Step 2 第1段階完了）:
  - `core/box/tiny_page_box.h` / `core/box/tiny_page_box.c` を追加し、`HAKMEM_TINY_PAGE_BOX_CLASSES` で有効クラスを制御できる Page Box を実装。
  - `tiny_tls_bind_slab()` から `tiny_page_box_on_new_slab()` を呼び出し、TLS が bind した C7 slab を per-thread の page pool に登録。
  - `unified_cache_refill()` の先頭に Page Box 経路を追加し、C7 では「TLS が掴んでいるページ内 freelist/carve」からバッチ供給を試みてから Warm Pool / Shared Pool に落ちるようにした（Box 境界は `Tiny Page Box → Warm Pool → Shared Pool` の順序を維持）。

### 性能の現状（Random Mixed, HEAD）
- 条件: `bench_random_mixed_hakmem 1000000 256 42`（1T, ws=256, RELEASE, 16–1024B）
  - HAKMEM: 約 5.0M ops/s
  - system malloc: 約 90–100M ops/s
  - mimalloc: 約 120–130M ops/s
- 条件: `bench_random_mixed_hakmem 1000000 256 42` +
  `HAKMEM_BENCH_MIN_SIZE=8 HAKMEM_BENCH_MAX_SIZE=128`（Tiny-only, 8–128B）
  - HAKMEM Tiny Front: 約 80–90M ops/s（mimalloc と同オーダー）
- 条件: `bench_random_mixed_hakmem 1000000 256 42` +
  `HAKMEM_BENCH_MIN_SIZE=129 HAKMEM_BENCH_MAX_SIZE=1024`（Tiny C5–C7 のみ）
  - HAKMEM: 約 4.7–4.8M ops/s
- 結論:
  - Tiny front 自体（8–128B）は十分速く、mimalloc と同オーダーまで出ている。
  - 129–1024B の Tiny C5–C7 経路で Unified Cache hit=0 / Shared Pool ロック多発というボトルネックがあり、
    Random Mixed 全体の性能を支配している。

### 次にやること（優先タスク：C7 Page Box の実効性検証とチューニング）
1. **C7 Page Box 経路の実効性を計測**
   - ENV: `HAKMEM_BENCH_MIN_SIZE=129 HAKMEM_BENCH_MAX_SIZE=1024` ＋ `HAKMEM_MEASURE_UNIFIED_CACHE=1` で
     `bench_random_mixed_hakmem 1000000 256 42` を実行し、C7 の:
     - Unified Cache refill 回数・平均 cycles
     - `shared_pool_acquire_slab(C7)` のロック回数
     を、Page Box ON/OFF（`HAKMEM_TINY_PAGE_BOX_CLASSES=` 未設定 vs `7`）で比較する。
2. **C7 の Unified Cache 容量・バッチサイズのチューニング**
   - `HAKMEM_TINY_UNIFIED_C7` と `unified_cache_refill()` の `max_batch` 設定を変えつつ、
     Page Box ON 時の C7 ヒット率・Shared Pool ロック回数・throughput を観測し、C7 にとって最適な容量/バッチサイズを探る。
3. **Page Box を C5/C6 に拡張するかの判断**
   - C7 で十分な効果（Shared Pool ロック大幅減 + throughput 向上）が得られた場合、
     `HAKMEM_TINY_PAGE_BOX_CLASSES=5,6,7` を試し、C5/C6 も Tiny-Plus 化したときの安定性・性能を確認する。
   - 問題がなければ、デフォルトプロファイルを「C5–C7 Page Box 有効」に近づけるかを検討する。

### メモ
- ページフォルト問題は Prefault Box + ウォームアップで一定水準まで解消済みで、現在の主ボトルネックはユーザー空間の箱（Unified Cache / free / Pool）側に移っている。
- 以降の最適化は「箱を削る」ではなく、「HOT 層で踏む箱を減らし、Tiny 的なシンプル経路をどこまで広げるか」にフォーカスする。