hakmem/docs/design/TINY_FRONT_V3_FLATTENING_GUIDE.md

TINY FRONT v3 FLATTENING GUIDE

Mixed 16–1024B で C7 v3 を ON にしたときの前段ホットパスを薄くするための設計メモ。実装は別フェーズ担当 AI 向けの TODO リストです。

現状の malloc_tiny_fast 前段フロー（ざっくり）

• size → 「Tiny かどうか」判定。
• Tiny なら size → class_idx (C0〜C7) 変換。
• route LUT (tiny_route_for_class(class_idx)) で route 決定。
• route switch で Tiny v1 / v2 / v3 / legacy を呼び分け。
• C7 v3 は早期パスで direct に so_alloc / so_free へ行くが、他クラスの前段 if/switch がまだ残っている。

perf で見えたボトルネック（Mixed 16–1024B, v3 ON, DEBUGビルド）

• tiny_region_id_write_header ~6.7%
• ss_map_lookup ~3.6%
• unified_cache_enabled ~2.8%, tiny_guard_is_enabled ~2.2%
• classify_ptr (size→class 判定) ~1.4%
• mid_desc_lookup ~1.3%
• so_alloc/so_free 自体は合計 ~7%（C7 v3 本体）。ここでは C7 以外の前段を削るのが目的。

フラット化方針（次フェーズで実装する項目）

1. size→class→route を 1 LUT + 1 switch に寄せる

   • C7 v3 の早期 if を最小限にし、C5/C6 などの分岐を共通 switch にまとめる。
   • route の再判定・重複チェックを減らす。デバッグ/稀パスは unlikely 側へ。

2. header/guard 系の前段整理

   • tiny_region_id_write_header の呼び出し回数・書き込みバイト数を確認し、必要最小限にする。
   • guard 判定 (tiny_guard_is_enabled など) を Snapshot 側に寄せ、front では値を読むだけにする。

3. Superslab 判定の軽量化

   • C7 v3 で self-thread が確定している場合の ss_map_lookup を避けられるか検討。
   • lookup が必要なケースを TinyLookupBox に閉じ込め、ホットパスは lookup なしで通す。

A/B 用プロファイル（固定）

• HAKMEM_BENCH_MIN_SIZE=16
• HAKMEM_BENCH_MAX_SIZE=1024
• HAKMEM_TINY_HEAP_PROFILE=C7_SAFE
• HAKMEM_TINY_C7_HOT=1
• HAKMEM_TINY_HOTHEAP_V2=0
• HAKMEM_POOL_V2_ENABLED=0
• HAKMEM_SMALL_HEAP_V3_ENABLED=1
• HAKMEM_SMALL_HEAP_V3_CLASSES=0x80
• ベンチ: ./bench_random_mixed_hakmem 1000000 400 1

成功ライン: 上記環境で v3 ON のまま +5〜10% か、少なくとも回帰なし＆ HEAP_STATS に異常なし。

Phase1 (done): フラグ判定のスナップショット化

• ENV ゲート:
  • HAKMEM_TINY_FRONT_V3_ENABLED … デフォルト OFF（有効時のみ v3 フロント経路）
  • HAKMEM_TINY_FRONT_V3_STATS … 任意のデバッグカウンタ用
• Snapshot（TinyFrontV3Snapshot）に
  • unified_cache_on
  • tiny_guard_on
  • header_mode を 1 回だけキャッシュし、front v3 ON のときは unified_cache_enabled / tiny_guard_is_enabled / tiny_header_mode の呼び出しをホットパスから排除。
• malloc/free とも snapshot を読むブロックに入り、UC/guard 判定をキャッシュ経由に統一。
• A/B（Mixed 16–1024B, ws=400, iters=1M, C7 v3 ON, Tiny/Pool v2 OFF）で挙動変化なし（slow=1 維持）。次は size→class 前段のフラット化に進める。

Phase2-A: size→class LUT 化（実装済み、A/B 待ち）

• ENV: HAKMEM_TINY_FRONT_V3_LUT_ENABLED（デフォルト OFF、v3 ON 時のみ有効化可能）。
• Tiny 前段専用の LUT (TinyFrontV3SizeClassEntry) を 1 回だけ構築し、front v3 が有効かつ LUT ON のときは malloc_tiny_fast が size→class→route を 1 ルックアップで取得（挙動は既存 hak_tiny_size_to_class / route スナップショットに一致）。
• フォールバック: LUT が無効/範囲外/未初期化のときは従来の size→class ロジックに自動で戻る。
• Mixed 16–1024B A/B（ws=400, iters=1M, C7 v3 ON, Tiny/Pool v2 OFF, front v3 ON）
  • LUT=0: 44.820M ops/s
  • LUT=1: 45.231M ops/s（+0.9%）
  • C7_PAGE_STATS: prepare_calls=2446（短尺時と同値）、HEAP_STATS は TinyHeap v1 経路外のため出力なし。
  • 挙動回帰なしで微プラス。次は size→class→route 前段のさらなるフラット化を検討。

Phase2-B: route fast path（LUT→1 switch）

• ENV: HAKMEM_TINY_FRONT_V3_ROUTE_FAST_ENABLED（デフォルト OFF、front v3 + LUT ON 時だけ opt-in）。
• 仕様:
  • size→class→route を LUT 2 バイト load で取得し、即 1 switch で v3/v2/v1/legacy に分岐。
  • route helper（tiny_route_for_class）呼び出しをホットパスから外し、挙動は LUT 構築時のスナップショットに従う。
  • ROUTE_FAST=0 のときは Phase2-A と同じ挙動に自動フォールバック。
• A/B（Mixed 16–1024B, ws=400, iters=1M, C7 v3 ON, Tiny/Pool v2 OFF, front v3 ON, LUT ON）
  • route_fast=0: 45.066M ops/s
  • route_fast=1: 44.821M ops/s（約 -0.5%）
  • C7_PAGE_STATS: prepare_calls=2446、回帰なし。HEAP_STATS は TinyHeap v1 経路外のため未出力。
• メモ: 微小マイナスだったためデフォルトは ROUTE_FAST=0 のまま。size→class 前段や header/guard 整理の方が効果が出そう。

Phase2-C: Header v3 (C7-only skip) 実験

• ENV:
  • HAKMEM_TINY_HEADER_V3_ENABLED（デフォルト 0）
  • HAKMEM_TINY_HEADER_V3_SKIP_C7（デフォルト 0、C7 v3 alloc 時に tiny_region_id_write_header をスキップして簡易 1byte だけ書く）
• 実装ポイント:
  • TinyFrontV3Snapshot に header_v3_{enabled,skip_c7} を追加。
  • so_alloc_fast(C7) で header_v3_skip_c7 が有効なときは header を簡易 1store のみで書き、ガード/重い処理を省略。
  • front/free 側の挙動は不変（ヘッダは class 判定用に 1byte だけ残す）。
• A/B（Mixed 16–1024B, ws=400, iters=1M, front v3/LUT ON, route_fast=0, C7 v3 ON）
  • header_v3=0: 44.29M ops/s, C7_PAGE_STATS prepare_calls=2446
  • header_v3=1 + SKIP_C7=1: 43.68M ops/s（約 -1.4%）, prepare_calls=2446, v3 fallback/page_of_fail=0
• 所感: 短尺の header スキップだけでは改善なし。free 側の header 依存を外す or header_light 再設計を別フェーズで検討。

Phase TF3: ptr fast classify（設計メモ / 実装TODO）

• ENV ゲート（デフォルト 0、A/B でのみ ON）
  • HAKMEM_TINY_PTR_FAST_CLASSIFY_ENABLED
• 目的: C7 v3 free の入口で「明らかに Tiny/C7 のページ」だけを fast path に送り、classify_ptr → ss_map_lookup → mid_desc_lookup の往復を避ける。外れたら必ず従来の classify_ptr 経路へフォールバックする。
• デザイン（free 側, malloc_tiny_fast.h 想定）:
  1. gate ＋ C7 v3 が有効かを Snapshot で確認（C6/Pool/off のときは何もしない）。
  2. ptr から TLS context / so_page_of / page metadata だけで「self-thread の C7 v3 ページ」かを判定。
  3. 判定 OK → ss_map_lookup を通さず C7 v3 の free 直行。
  4. 判定 NG → 現行の classify_ptr/ss_map_lookup にそのまま落とす（Box 境界は不変）。
• 実装担当向け TODO:
  • ENV gate 追加（デフォルト 0）。
  • free 入口に C7 v3 専用 fast classify を追加（必ずフォールバックあり）。
  • A/B: Mixed 16–1024B, C7 v3 ON, front v3/LUT ON, Tiny/Pool v2 OFF
    • baseline: PTR_FAST_CLASSIFY=0
    • trial: PTR_FAST_CLASSIFY=1
    • 期待: segv/assert なし、ss_map_lookup / classify_ptr self% 減、ops/s が +数%〜+10% 方向。

実装後メモ（2025/TF3）

• 実装: tiny_ptr_fast_classify_enabled ゲート追加、free 入口で C7 v3 の TLS ページ判定（smallobject_hotbox_v3_can_own_c7）が当たれば so_free へ直行。外れは従来 route/classify へフォールバック。
• Mixed 16–1024B (C7-only v3, front v3+LUT ON, v2/pool v2 OFF, ws=400, iters=1M, Release):
  • OFF: 33.9M ops/s → ON: 36.7M ops/s（約 +8.1%）。
• DEBUG perf (cycles@5k, dwarf, gate=1): ss_map_lookup self が 7.3% → 0.9%、hak_super_lookup はトップ外へ。TLS 走査 (smallobject_hotbox_v3_can_own_c7) が ~5.5% に現れるが lookup 往復より低コスト。
• ロールアウト案: Mixed 基準でプラスが安定しているため、front v3/LUT ON 前提では fast classify もデフォルトON候補。ENV=0 で即オフに戻せる構造は維持。

メモ: gate 大規模再構成（TG2）は回帰で撤退

• tiny_alloc_gate_box を「size→class→route 判定を前段に集約」する形に再構成し、malloc_tiny_fast_dispatch を導入したが、Mixed 16–1024B (MIXED_TINYV3_C7_SAFE, Release) で 約 -14% の回帰を確認。
• 変更は破棄し、gate は従来の薄いラッパに戻した。今後は gate 全体をいじらず、ヘッダ書き込み削減・ptr classify・header/route snapshot 等の局所的枝刈りで進める。