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) 判定

// 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 で応用