hakmem/docs/design/POOL_HOTBOX_V2_IMPLEMENTATION_GUIDE.md

POOL_HOTBOX_V2_IMPLEMENTATION_GUIDE (Phase68 スケルトン)

目的

• pool allocator のホットパスを TinyHotHeap v2 と同様に Hot/Cold 分離するための実装ガイド。
• 現行 v1 をデフォルトのまま残しつつ、ENV ゲートで v2 を A/B できる形で段階的に導入する。

前提・ゲート

• デフォルトは v1（HAKMEM_POOL_V2_ENABLED=0）。v2 は bench/研究用に opt-in。
• クラスマスクを追加する場合は HAKMEM_POOL_V2_CLASSES（bit per class）を想定。

実装ステップ

1. 型整備（Hot Box）

   • pool_page_v2（freelist/used/capacity/base/meta/token）
   • pool_class_v2（current_page/partial_pages/full_pages/stride）
   • pool_ctx_v2（全クラス配列）

2. TLS 初期化

   • pool_v2_tls_get() を追加し、calloc + memset で ctx を用意。
   • 各クラスの block_size/stride を初期化。max_partial_pages 等のポリシー値もここで設定。

3. alloc/free Hot パス

   • pool_v2_alloc(class_idx):
     • current → partial → refill の順で freelist pop、page 内 used++。
   • pool_v2_free(class_idx, ptr):
     • page_of(ptr) を求め、freelist push / used--。
     • used==0 なら retire 判定（partial 上限を超えたら Cold へ返却）。
   • Hot パスでは OS/Stats/学習に触れない。

4. Cold IF

   • PoolColdIface を定義 (refill_page, retire_page)。
   • 初期実装は既存 pool/superslab の refill/retire API をラップして流用し、Hot からは IF だけを見る。

5. Gate/Route

   • front 入口は 1 LUT + switch（route）で v1/v2/legacy を選択。
   • HAKMEM_POOL_V2_ENABLED / classes mask で v2 を有効化し、fallback は常に v1 へ。

6. Stats/Fail-Fast

   • ENV で有効化できる軽量 stats（alloc_fast/slow/refill/fallback, free_fast/retire 等）を用意。
   • 不整合（class mismatch/範囲外）は Fail-Fast、フォールバックは明示的にカウントする。

ベンチ計画（目安）

• プロファイル: ./bench_mid_large_mt_hakmem 1 1000000 400 1（Release, C7_SAFE, v2 OFF が基準）。
• 目標: 28–29M ops/s → 30–32M (+5〜10%)。perf stat で cycles を明確に下げる。

メモ

• Superslab/OS/Stats/Learning のロジックは変えない。Cold IF を挟んで境界を明確にするだけ。
• C6-heavy など特定クラスから段階的に v2 を試し、回帰が出たら即ゲートで戻せる構造を優先する。***