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/5/6（C6/C5 v4 の診断と一時凍結）** ✅ 完了
   - C5 v4:
     - C5-heavy (129–256B): v4 OFF **54.4M** → v4 ON **48.7M ops/s**（−10〜11% 回帰）。既存 Tiny/front v3 経路が速い。
     - Mixed 16–1024B では C5+C6 v4 ON で +2〜3% 程度の微改善だが、本線として採用するほどのメリットは無い。
   - C6 v4:
     - 正しい C6-only ベンチ（MIN=256 MAX=510）で v4 OFF **~58–67M** → v4 ON **~48–50M ops/s**（−15〜28% 回帰）。
     - stats から C6 alloc/free の 100% が v4 経路を通っていることが確認でき、route/fallback ではなく v4 実装そのものが重いことが判明。
     - ws/iters を増やすと TinyHeap とページ共有する設計起因のクラッシュも残存しており、C6 v4 を現行設計のまま本線に載せるのは難しい。
   - TLS fastlist:
     - C6 用 TLS fastlist を追加したが、v4 ON 時の C6-heavy throughput はほぼ変わらず（48〜49M ops/s）。根本的な回帰（v4のページ管理/構造）を打ち消すには至っていない。
   - 方針:
     - SmallObject v4（C5/C6 向け）は当面 **研究箱のまま凍結**し、本線の mid/smallmid 改善は別設計（small-object v5 / mid-ULTRA / pool 再設計）として検討する。
     - Mixed/C7 側は引き続き「C7 v3 + C7 ULTRA」を基準に A/B を行い、mid/pool 側は現行 v1 を基準ラインとして据え置く。

3. **Phase v4-mid-SEGV（C6 v4 の SEGV 修正・研究箱安定化）** ✅ 完了
   - **問題**: C6 v4 が TinyHeap のページを共有 → iters >= 800k で freelist 破壊 → SEGV
   - **修正**: C6 専用 refill/retire を SmallSegment v4 に切り替え、TinyHeap 依存を完全排除
   - **結果**:
     - iters=1M, ws <= 390: **SEGV 消失** ✅
     - C6-only (MIN=257 MAX=768): v4 OFF ~47M → v4 ON ~43M ops/s（−8.5% 回帰のみ、安定）
     - Mixed 16–1024B: v4 ON で SEGV なし（小幅回帰許容）
   - **方針**: C6 v4 は研究箱として**安定化完了**。本線には載せない（既存 mid/pool v1 を使用）。

4. **Phase v5-0（SmallObject v5 refactor: ENV統一・マクロ化・構造体最適化）** ✅ 完了
   - **内容**: v5 基盤の改善・最適化（挙動は完全不変）
   - **改善項目**:
     - ENV initialization を sentinel パターンで統一（ENV_UNINIT/ENABLED/DISABLED + `__builtin_expect`）
     - ポインタマクロ化: `BASE_FROM_PTR`, `PAGE_IDX`, `PAGE_META`, `VALIDATE_MAGIC`, `VALIDATE_PTR`
     - SmallClassHeapV5 に `partial_count` 追加
     - SmallPageMetaV5 の field 再配置（hot fields 先頭集約 → L1 cache 最適化, 24B）
     - route priority ENV 追加: `HAKMEM_ROUTE_PRIORITY={v4|v5|auto}`
     - segment_size override ENV 追加: `HAKMEM_SMALL_HEAP_V5_SEGMENT_SIZE`
   - **挙動**: 完全不変（v5 route は呼ばれない、ENV デフォルト OFF）
   - **テスト**: Mixed 16–1024B で 43.0–43.8M ops/s（変化なし）、SEGV/assert なし
   - **目標**: v5-1 で C6-only stub → v5-2 で本実装 → v5-3 で Mixed に段階昇格

5. **Phase v5-1（SmallObject v5 C6-only route stub 接続）** ✅ 完了
   - **内容**: C6 を v5 route に接続（中身は v1/pool fallback）
   - **実装**:
     - `tiny_route_env_box.h`: C6 で `HAKMEM_SMALL_HEAP_V5_ENABLED=1` なら `TINY_ROUTE_SMALL_HEAP_V5` に分岐
     - `malloc_tiny_fast.h`: alloc/free switch に v5 case 追加（fallthrough で v1/pool に落ちる）
     - `smallobject_hotbox_v5.c`: stub 実装（alloc は NULL 返却、free は no-op）
   - **ENV**: `HAKMEM_SMALL_HEAP_V5_ENABLED=1` / `HAKMEM_SMALL_HEAP_V5_CLASSES=0x40` で opt-in
   - **テスト結果**:
     - C6-heavy: v5 OFF ~15.5M → v5 ON ~16.4M ops/s（変化なし, 正常）
     - Mixed: 47.2M ops/s（変化なし）
     - SEGV/assert なし ✅
   - **方針**: v5-1 では挙動は v1/pool fallback と同じ。研究箱として ENV プリセット（`C6_SMALL_HEAP_V5_STUB`）を `docs/analysis/ENV_PROFILE_PRESETS.md` に追記。v5-2 で本実装を追加。

---

### 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/*` を参照してください。