hakmem/CURRENT_TASK.md

## HAKMEM 状況メモ（コンパクト版, 2025-12-10）

このファイルは「いま何を基準に A/B するか」「どの箱が本線か」だけを短くまとめたものです。  
過去フェーズの詳細なログは `CURRENT_TASK_ARCHIVE_20251210.md` と各 `docs/analysis/*` に残しています。

---

### 1. ベースライン（1 thread, ws=400, iters=1M, seed=1）

- **Mixed 16–1024B（本線）**
  - コマンド: `HAKMEM_PROFILE=MIXED_TINYV3_C7_SAFE ./bench_random_mixed_hakmem 1000000 400 1`
  - 主な ENV（bench_profile 経由）:
    - `HAKMEM_TINY_HEAP_PROFILE=C7_SAFE`
    - `HAKMEM_TINY_C7_HOT=1`
    - `HAKMEM_SMALL_HEAP_V3_ENABLED=1` / `HAKMEM_SMALL_HEAP_V3_CLASSES=0x80`（C7-only v3）
    - `HAKMEM_TINY_C7_ULTRA_ENABLED=1`（UF-3 セグメント版, 2MiB/64KiB）
    - `HAKMEM_TINY_FRONT_V3_ENABLED=1` / `HAKMEM_TINY_FRONT_V3_LUT_ENABLED=1`
    - `HAKMEM_POOL_V2_ENABLED=0`
  - Throughput（現 HEAD, Release）: **約 44–45M ops/s**
  - 競合:
    - mimalloc: ~110–120M ops/s
    - system: ~90M ops/s

- **C7-only (1024B 固定, C7 v3 + ULTRA)**  
  - C7 ULTRA OFF: ~38M ops/s  
  - C7 ULTRA ON:  ~57M ops/s（約 +50%以上）  
  - C7 向け設計（ULTRA セグメント + TLS freelist + mask free）は成功パターンとみなし、今後の small-object v4/mid に展開予定。

- **C6-heavy mid/smallmid (257–768B, C6 は mid/pool 経路)**
  - コマンド: `HAKMEM_PROFILE=C6_HEAVY_LEGACY_POOLV1 ./bench_mid_large_mt_hakmem 1 1000000 400 1`
  - 現状 Throughput: **約 10M ops/s**
  - 過去 Phase82 では LEGACY + flatten で 23–27M ops/s を記録しており、現行 HEAD では lookup 層（hak_super_lookup/mid_desc_lookup 等）がボトルネック化している状態。

---

### 2. いま本線で有効な箱

1. **C7 v3 + C7 ULTRA (UF-3 セグメント版)**  
   - Hot: TinyC7UltraBox（TLS freelist + 2MiB Segment / 64KiB Page, mask 判定）。  
   - Cold: C7UltraSegmentBox（page_meta[] で page/class/used/capacity を管理）。  
   - 特徴:
     - C7-only で ~38M→~57M ops/s。Mixed でも 35M→44–45M ops/s まで底上げ。  
     - C7 ULTRA 管理外の ptr は必ず C7 v3 free にフォールバック（ヘッダ付き Fail-Fast 経路を維持）。  
   - ENV:
     - `HAKMEM_TINY_C7_ULTRA_ENABLED=1`（デフォルト ON）  
     - `HAKMEM_TINY_C7_ULTRA_HEADER_LIGHT` は研究箱（デフォルト 0）。

2. **SmallObject v3（C7-only 本線）**
   - C7 ページ単位の freelist + current/partial 管理。ColdIface は Tiny v1 経由で Superslab/Warm/Stats を触る。  
   - C7 ULTRA ON 時は「セグメント内 ptr だけ ULTRA が先に食い、残りは v3 free」が基本構造。

3. **mid/pool v1（C6 は一旦ここに固定, Phase C6-FREEZE）**
   - C6 は Tiny/SmallObject/ULTRA で特別扱いしない。  
   - C6 専用 smallheap v3/v4/ULTRA・pool flatten はすべて ENV opt-in の研究箱扱い。  
   - 現状 C6-heavy は ~10M ops/s。再設計ターゲット。

---

### 3. small-object v4 / mid 向けの現状と方針

- **SmallObjectHotBox_v4 の箱構造（設計済み, 部分実装）**
  - `SmallPageMeta`: `free_list/used/capacity/class_idx/flags/page_idx/segment`。
  - `SmallClassHeap`: `current/partial_head/full_head`。  
  - `SmallHeapCtx`: per-thread で `SmallClassHeap cls[NUM_SMALL_CLASSES]` を持つ。
  - `SmallSegment` (v4): 2MiB Segment / 64KiB Page を前提に `page_meta[]` を持つ。  
  - ColdIface_v4: `small_cold_v4_refill_page` / `small_cold_v4_retire_page` / `small_cold_v4_remote_push/drain` の 1 箱。

- **C6-only v4 実装（Phase v4-mid-2, 研究箱）**
  - C6 の alloc/free を SmallHeapCtx v4 経由で処理し、Segment v4 から refill/retire する経路を実装済み。  
  - C6-heavy A/B（C6 v1 vs v4）:
    - v4 OFF: ~9.4M ops/s  
    - v4 ON : ~10.1M ops/s（約 +8〜9%）  
  - Mixed で C6-only v4 を ON にすると +1% 程度（ほぼ誤差内）で回帰なし。
  - デフォルトでは `HAKMEM_SMALL_HEAP_V4_ENABLED=0` / `CLASSES=0x0` のため標準プロファイルには影響しない。

- **mid/smallmid の今後の狙い**
  - 現状：C6-heavy ~10M ops/s、lookup 系（hak_super_lookup / mid_desc_lookup / classify_ptr / ss_map_lookup）が ~40% を占める。  
  - 方向性：  
    - C7 ULTRA で成功したパターン（Segment + Page + TLS freelist + mask free）を small-object v4 に広げて、ptr→page→class を O(1) にする。  
    - mid_desc_lookup / hak_super_lookup などの lookup 層を small-object v4 route から外す。  
    - C6/C5 は「hot mid クラス」として段階的に v4 に載せ、その他の mid/smallmid は SmallHeap v4 or pool v1 で扱う。

---

### 4. 今後のフェーズ（TODO 概要）

1. **Phase v4-mid-3（C5-only v4 研究箱）** ✅ 完了
   - ENV: `HAKMEM_SMALL_HEAP_V4_ENABLED=1` / `HAKMEM_SMALL_HEAP_V4_CLASSES=0x20` で C5 を SmallHeap v4 route に載せる。
   - A/B 結果:
     - C5-heavy (129–256B): v4 OFF **54.4M** → v4 ON **48.7M ops/s** (−10〜11%回帰)。既存 Tiny/front v3 経路が速い。
     - Mixed 16–1024B (C6+C5 v4): C6-only **28.3M** → C5+C6 **28.9M ops/s** (+2%, 誤差〜微改善)。回帰なし。
   - 方針: C5-heavy では v4 が劣後するため、C5 v4 は研究箱のまま標準プロファイルには入れない。Mixed では影響小さいため C5+C6 v4 (0x60) も研究箱として利用可能。

2. **Phase v4-mid-4（C6 v4 perf 可視化）** ✅ 完了
   - **重要な発見**: `bench_mid_large_mt_hakmem` は 8〜32 KiB を生成するため、C6 v4 を測定できていなかった。
   - 正しい C6-only ベンチ (`bench_random_mixed_hakmem` + `MIN=256 MAX=510`):
     - v4 OFF: **66.7M ops/s**
     - v4 ON: **48.0M ops/s** (−28% 回帰)
   - perf: `small_heap_alloc_fast_v4` が上位に出てこない。v4 alloc が正しく呼ばれていない可能性。
   - 次ステップ: v4 route が正しく呼ばれているか確認・修正が必要。

3. **Phase v4-mid-5（C6 v4 alloc パス修正と診断）** ✅ 完了
   - **問題**: Phase v4-mid-4 で `small_heap_alloc_fast_v4` が perf に出現せず、v4 route が正しく呼ばれているか不明だった。
   - **修正**: 箱化モジュール化の原則に従い、統計 box (`smallobject_hotbox_v4_stats_box.h`) を追加し、alloc/free 経路にカウンタを仕込んだ。
   - **診断結果** (C6-only bench, MIN=256 MAX=510):
     - v4 OFF: **58.2M ops/s**
     - v4 ON: **49.5M ops/s** (−15% 回帰)
     - Stats: C6 alloc 25,063 calls (100% success, 0 fallback), C6 free 25,062 calls (100% page_found)
   - **結論**: v4 route は正しく動作しているが、v4 実装が pool v1 より遅い。次フェーズで perf を取り、ホットスポットを特定する必要がある。

4. **Phase v4-mid-6 以降**
   - C6 v4 の perf プロファイルを取り、ホットスポット（refill/retire/freelist 操作など）を特定
   - C7 ULTRA で成功したパターン（mask 判定・TLS freelist）を v4 に統合
   - mid/smallmid で `mid_desc_lookup / hak_super_lookup` の self% を段階的に削り、Mixed 16–1024B 全体を mimalloc の 50〜60M ops/s に近づけていく。

5. **ヘッダレスの統合（後フェーズ）**
   - いまは C7 ULTRA だけが Segment+mask 基盤で動いている。
   - small-object v4 が安定したら、C7 ULTRA のヘッダレス設計を SmallHeapCtx v4 にも展開する（ptr→page→class→page meta でヘッダ不要に近づける）。  
   - そのうえで header/light/off は別箱（HeaderBox）として opt-in できるようにする。

---

### 5. 健康診断ラン（必ず最初に叩く 2 本）

- Tiny/Mixed 用:
  ```sh
  HAKMEM_PROFILE=MIXED_TINYV3_C7_SAFE \
  ./bench_random_mixed_hakmem 1000000 400 1
  # 目安: 44±1M ops/s / segv/assert なし
  ```

- mid/smallmid C6 用:
  ```sh
  HAKMEM_PROFILE=C6_HEAVY_LEGACY_POOLV1 \
  ./bench_mid_large_mt_hakmem 1 1000000 400 1
  # 現状: ≈10M ops/s / segv/assert なし（再設計ターゲット）
  ```

まとめて叩きたいときは `scripts/verify_health_profiles.sh`（存在する場合）を利用し、  
詳細な perf/フェーズログは `CURRENT_TASK_ARCHIVE_20251210.md` と各 `docs/analysis/*` を参照してください。