hakmem/CURRENT_TASK.md

# CURRENT TASK – Phase 13 (TinyHeapV2 / Tiny + Mid 状況メモ)

**Date**: 2025-11-15  
**Status**: 🟡 TinyHeapV2 = 安全な stub / 供給未実装, Mid = 完了, SP‑SLOT = 完了  
**Owner**: ChatGPT → 次フェーズ実装担当: Claude Code

---

## 1. 全体の今どこ

- Tiny (0–1023B):
  - Front: NEW 3-layer front (bump / small_mag / slow) 安定。
  - TinyHeapV2: 「alloc フロント＋統計」実装済みだが、magazine 供給なし → hit 率 0%。
  - Drain: TLS SLL drain interval = 2048（デフォルト）。Tiny random mixed で ~9M ops/s レベル。
- Mid (1KB–32KB):
  - GAP 修正済み: `MID_MIN_SIZE=1024` に下げて 1KB–8KB を Mid が担当。
  - Pool TLS ON デフォルト（mid ベンチ）で ~10.6M ops/s（System malloc より速い）。
- Shared SuperSlab Pool (SP‑SLOT Box):
  - 実装完了。SuperSlab 数 -92%、mmap/munmap -48%、Throughput +131%。
  - Lock contention (Stage 2) は P0-5 まで実装済み、+2–3% 程度の改善。

結論: Mid / Shared Pool 側は「研究目的としては一旦完了」。  
残りの大きな余白は **Tiny front（C0–C3）** と **一部 Tiny ベンチ (Larson / 1KB fixed)**。

---

## 2. TinyHeapV2 Box の現状

### 2.1 実装済み (Phase 13-A – Alloc Front)

- Box: `TinyHeapV2`（per-thread magazine front, C0–C3 用の L0 キャッシュ）
- ファイル:
  - `core/front/tiny_heap_v2.h`
  - `core/hakmem_tiny.c`（TLS 定義 + 統計出力）
  - `core/hakmem_tiny_alloc_new.inc`（alloc hook）
- TLS 構造:
  - `__thread TinyHeapV2Mag   g_tiny_heap_v2_mag[TINY_NUM_CLASSES];`
  - `__thread TinyHeapV2Stats g_tiny_heap_v2_stats[TINY_NUM_CLASSES];`
- ENV:
  - `HAKMEM_TINY_HEAP_V2` → Box ON/OFF。
  - `HAKMEM_TINY_HEAP_V2_CLASS_MASK` → bit0–3 で C0–C3 有効化。
  - `HAKMEM_TINY_HEAP_V2_STATS` → 統計出力 ON。
  - `HAKMEM_TINY_HEAP_V2_DEBUG` → 初期デバッグログ。
- 振る舞い:
  - `hak_tiny_alloc(size)` が C0–C3 かつ mask OK のとき `tiny_heap_v2_alloc(size)` を先に試す。
  - `tiny_heap_v2_alloc`:
    - mag.top>0 なら pop（BASE を返す）→ `HAK_RET_ALLOC` で header + user に変換。
    - mag 空なら **即 NULL** を返し、既存 front へフォールバック。
  - `tiny_heap_v2_refill_mag` は NO-OP（refill なし）。
  - `tiny_heap_v2_try_push` は実装済みだが、まだ実際の free/alloc 経路から呼ばれていない想定で OK（Phase 13-B で使う）。
- 現状の性能:
  - 16/32/64B fixed-size (100K) で ±1% 以内 → hook オーバーヘッドはほぼゼロ。
  - `alloc_calls` は 200K まで増えるが `mag_hits=0`（supply なしのため）。

**要点:** TinyHeapV2 は「壊さず差し込めた L0 stub」。  
これから **supply をどう設計するか** が Phase 13-B の主題。

---

## 3. 最近のバグ修正・仕様調整（もう触らなくてよい箱）

### 3.1 Tiny / Mid サイズ境界ギャップ修正（完了）

- 以前:
  - `TINY_MAX_SIZE = 1024` / `MID_MIN_SIZE = 8192` で 1KB–8KB が誰の担当でもなく mmap 直行。
- 今:
  - Tiny: `TINY_MAX_SIZE = 1023`（ヘッダ 1B 前提で 1023B まで Tiny）。
  - Mid:  `MID_MIN_SIZE = 1024`（1KB–32KB を Mid MT が処理）。
- 効果:
  - `bench_fixed_size_hakmem 1024B` が mmap 地獄から脱出 → Mid MT 経路で ~0.5M ops/s レベルに改善。
  - SEGV は解消。今残っているのは性能ギャップだけ（TinyHeapV2 とは独立）。

### 3.2 Shared Pool / LRU / Drain 周り

- TLS SLL drain:
  - `HAKMEM_TINY_SLL_DRAIN_INTERVAL` デフォルト = 2048。
  - 128/256B 固定サイズで A/B 済み。どちらも退化なく、むしろ +5〜+15% 程度の改善。
- SP‑SLOT Box:
  - SuperSlab 数削減・syscall 削減は期待通り。  
  - futex / lock contention は P0-5 まで対処済み（追加改善は高コスト領域として一旦後回し）。

---

## 4. Phase 13-B – TinyHeapV2: 次にやること

目的: TinyHeapV2 に **安全な供給経路** を付けて、C0–C3 を 2–5x くらい速くできるか検証する。  
（Tiny front の研究用 Box。失敗しても ENV で即 OFF に戻せるようにする。）

### 4.1 Box 境界のルール

- TinyHeapV2 は **front-only Box** として扱う:
  - Superslab / shared pool / drain には触らない。
  - 既存の SLL / FastCache / small_mag の invariants は壊さない。
- supply は「おこぼれ」スタイル:
  - 既存 front / free が確定的に成功したあと、その結果の一部を TinyHeapV2 にコピーするだけ。
  - primary owner は従来の front/back。TinyHeapV2 が壊れても allocator 全体は壊れないようにする。

### 4.2 具体的 TODO（Claude Code 君向け）

1. **現行 free/alloc 経路の確認（ドキュメント化のみ）**
   - `core/box/hak_free_api.inc.h` の Tiny 分岐:
     - `classify_ptr` → `PTR_KIND_TINY_HEADER` → `hak_tiny_free_fast_v2` / `hak_tiny_free`。
   - `core/hakmem_tiny_alloc_new.inc` の C0–C3 経路:
     - bump / small_mag / slow path のヒット点をざっくりメモ。
   - ここではコード変更より「どの箱を通っているかの図」を更新するのが目的。

2. **Step 13-B-1: alloc 側からの supply（低リスク）**
   - 対象: C0–C2（8/16/32B）だけに限定して開始。
   - 場所候補: `hakmem_tiny_alloc_new.inc` の各「成功パス」の直前:
     - 例: small_mag ヒットして BASE が決まった直後、`HAK_RET_ALLOC` の直前で:
       - `tiny_heap_v2_try_push(class_idx, base);` を 1 回だけ呼ぶ（ENV / class mask でガード）。
   - ルール:
     - 1 alloc で push してよいのは高々 1 ブロック。
     - TinyHeapV2 の mag が満杯なら何もしない（元のパスに影響を与えない）。
   - 検証:
     - 16/32B fixed-size を対象に:
       - `HAKMEM_TINY_HEAP_V2=1`, `..._CLASS_MASK` を C1/C2 のみにして A/B。
       - `mag_hits` が >0 になること。
       - ベースラインから退化しないこと（±5% 以内）。

3. **Step 13-B-2: free 側からの supply（中リスク、後半）**
   - 条件: Step 13-B-1 で「挙動 OK / 性能悪化なし」が確認できてから着手。
   - 方針:
     - `hak_free_at` の Tiny 分岐、same-thread fast path の **最後** に TinyHeapV2 への push を検討。
     - すでに SLL / FastCache に戻したあとで「余剰分」を TinyHeapV2 にコピーする形にする。
   - ここはまだ設計だけで OK（実装は後続フェーズでも良い）。

4. **Step 13-C: 評価・チューニング**
   - ENV 組み合わせ:
     - `HAKMEM_TINY_HEAP_V2=1`
     - `HAKMEM_TINY_HEAP_V2_CLASS_MASK` で C0〜C3 を個別に ON/OFF。
   - 指標:
     - `mag_hits / alloc_calls`（hit 率）:
       - 目標: C1/C2 で 30–60% 程度 hit すれば成功。
     - 性能:
       - fixed-size 16/32B: 既存 ~10M ops/s → 15–20M を狙う（+50–100%）。
   - コード側は Box 境界を守りつつ、mag size, 対象 class, supply トリガ条件などを調整。

---

## 5. 「今は触らない」領域メモ

- Mid-Large allocator（Pool TLS + lock-free Stage 1/2）:
  - SEGV 修正済み、futex 95% 削減、8T で +896% 改善。
  - 現時点では研究テーマとしては十分進んだので、Tiny に集中して OK。
- Larson ベンチの 100x 差:
  - Lock contention / metadata 再利用の問題が絡む大きめのテーマ。
  - TinyHeapV2 がある程度形になってから、別 Phase で攻める。

---

## 6. まとめ（Claude Code 用の一言メモ）

- **箱の境界**: TinyHeapV2 は「front-only L0 Cache Box」。Superslab / Pool / Drain には触らない。
- **今すぐやること**: alloc 側からの「おこぼれ supply」を 1 箇所だけ差し込んで、統計と A/B を取る。
- **free 側の統合**: 設計だけ整理しておき、実装は TinyHeapV2 の挙動を見てからで大丈夫。