hakmem/docs/analysis/SMALLOBJECT_V5_DESIGN.md

# SmallObject HotBox v5 設計ドキュメント

## 目的

16〜2KiB 帯の small-object/mid を **SmallObjectHotBox_v5** に集約し、Mixed 16–1024B を **mimalloc の 5割（50〜60M ops/s）** クラスに寄せる。

v4 は「TinyHeap 依存 + 重い page 管理」の反省対象として archive。C5/C6 は v4 ではなく **v5 に乗せる**。

---

## 箱構造

### Hot Path: SmallObjectHotBox_v5
- **型**: `SmallHeapCtxV5` (per-thread)
- **状態**: `SmallClassHeapV5 cls[NUM_SMALL_CLASSES_V5]` (current/partial/full リスト)
- **特徴**: ptr→page→class を O(1) で判定、mid_desc_lookup / hak_super_lookup / classify_ptr を呼ばない

### Cold Path: SmallColdIface_v5
- `small_cold_v5_refill_page()`: ページ割当
- `small_cold_v5_retire_page()`: ページ返却
- `small_cold_v5_remote_push()`: リモート free
- `small_cold_v5_remote_drain()`: バッチ回収

### Segment: SmallSegmentBox_v5
- **構成**: 2MiB Segment / 64KiB Page
- **ページメタ**: `SmallPageMetaV5 page_meta[]` (class_idx/used/capacity/freelist を直接保持)
- **O(1) lookup**: Segment mask + page_idx で `page_meta` に直接アクセス
- **API**:
  - `small_segment_v5_acquire()`: セグメント確保
  - `small_segment_v5_page_meta_of()`: ptr → page_meta

### Policy/Learning: SmallPolicySnapshot_v5
- `route_kind` (TINY, SMALL_HEAP_V5, POOL_V1 など)
- `block_size` (各サイズクラスの実サイズ)
- `max_partial_pages` (partial リスト上限)
- Route/Policy 変更時に snapshot を再計算（lazy initialization）

---

## 設計の芯

### 1. ptr→page→class の O(1) 判定
```c
// SmallSegment mask計算
SmallPageMetaV5* meta = small_segment_v5_page_meta_of(ptr);
// ↓ Segment base + (ptr - base) / PAGE_SIZE で直接インデックス計算
```
- TinyHeap lookup を呼ばない
- mid_desc_lookup / hak_super_lookup を呼ばない
- SmallSegment が所有するページなら即座に class_idx 取得可能

### 2. Hot/Cold の分離
- **Hot**: current/partial リスト + TLS freelist (将来)
- **Cold**: SmallSegment ページプール + remote push/drain
- C7 ULTRA は L0 lane として維持、v5 は影響されず動く

### 3. C7 ULTRA との共存
- C7 ULTRA は「超ホットクラス専用 lane」として後段フェーズで検討
- v5 は C7 ULTRA に依存しない（ULTRA が OFF でも v5 は動く）
- Segment/Policy は共有可能（内部実装は後で詰める）

### 4. クラス対象
- **初期**: C6（257–768B）→ C5（129–256B）
- **将来**: C4（65–128B）以下
- C7（1024B）は ULTRA lane で十分だが、必要に応じて v5 也の optimize lane も検討

---

## フェーズ案

### Phase v5-0: 型・IF・ENV のみ（完全 OFF）
- `SmallObjectHotBox_v5_box.h`: 型定義
- `SmallSegmentBox_v5.h`: Segment 構造定義
- `SmallColdIface_v5.h`: Cold function 宣言（stub）
- `SmallObjectV5_env_box.h`: ENV ゲート（HAKMEM_SMALL_HEAP_V5_ENABLED=0 デフォルト）
- `smallobject_hotbox_v5.c`: HotBox 実装 stub（fallback）
- **挙動**: 完全不変、v5 route は呼ばれない

### Phase v5-1: C6-only v5 route stub（front 経路だけ通す）
- tiny_route に `TINY_ROUTE_SMALL_HEAP_V5` 追加
- ENV で `HAKMEM_SMALL_HEAP_V5_ENABLED=1 HAKMEM_SMALL_HEAP_V5_CLASSES=0x40` で C6 を v5 route に
- 中身は v1/pool fallback → v5-0 段階での A/B（route 経由は OK か確認）

### Phase v5-2: C6-only v5 本実装（Segment + Page + TLS freelist）
- SmallSegment v5 の割当・ページ carve 実装
- SmallHeapCtx v5 の alloc/free 実装
- C6-heavy ベンチで v1 と A/B
- 目標: -10% 以下の回帰で安定

### Phase v5-3: Mixed での段階的 v5 昇格
- hot class（C6 → C5 → C4）から順次 v5 に載せる
- Mixed 16–1024B で 50–60M ops/s を目指す
- C7 ULTRA と v5 の共存 tuning

---

## 実装上の注意

1. **v4 との区別**: すべてのシンボルに `*_v5` suffix をつける → binary に両方いても競合しない
2. **fallback**: v5 enabled だが route に乗らない class は既存 v1/pool に自動 fallback
3. **route snapshot**: tiny_route_snapshot_init() で policy を計算 (per-thread, lazy)
4. **segment pool**: SmallSegment v5 は thread-local or global pool から取得（詳細は v5-2 で）

---

## ターゲット性能

| Workload | v4/v3 | v5 目標 | vs mimalloc |
|----------|-------|--------|------------|
| C6-only (257–768B) | ~43M (v4) / ~47M (v1) | ~45–48M | − |
| C5-heavy (129–256B) | ~49M (v1) | ~48–50M | − |
| Mixed 16–1024B | ~44–45M | ~50–60M | ~50% |

---

## 依存関係

- `SmallSegmentBox_v5`: SmallPageMetaV5 を直接管理
- `SmallColdIface_v5`: SmallSegmentBox_v5 に refill/retire 依頼
- `SmallObjectHotBox_v5`: SmallColdIface_v5 を呼ぶ
- tiny_route: SmallObjectHotBox_v5 へ C6/C5/... route
- policy/env: SmallObjectV5_env_box で class mask 管理

---

## アーカイブ参照

- `SmallObjectHotBox_v4`: TinyHeap 依存がある、page 管理が重い → v5 の反省対象
- `Phase v4-mid-SEGV`: C6 v4 の SEGV 修正で SmallSegment 独立化済み → v5 で応用