83d4096fbc
設計ドキュメント: - docs/analysis/SMALLOBJECT_V5_DESIGN.md: v5 アーキテクチャ全体設計 新規ファイル (v5 スケルトン): - core/box/smallobject_hotbox_v5_box.h: HotBox v5 型定義 - core/box/smallsegment_v5_box.h: Segment v5 型定義 - core/box/smallobject_cold_iface_v5.h: ColdIface v5 IF宣言 - core/box/smallobject_v5_env_box.h: ENV ゲート - core/smallobject_hotbox_v5.c: 実装 stub (完全 fallback) 特徴: ✅ 型とインターフェースのみ定義（v5-0 は機能なし） ✅ ENV デフォルト OFF（HAKMEM_SMALL_HEAP_V5_ENABLED=0） ✅ 挙動完全不変（Mixed/C6 benchmark 確認済み） ✅ v4 との区別を明確化 (*_v5 suffix) ✅ v5-1 (stub) → v5-2 (本実装) → v5-3 (Mixed) への段階実装準備完了 フェーズ: - v5-0: 型定義のみ（現在） - v5-1: C6-only stub route 追加 - v5-2: Segment/HotBox 本実装 (C6-only bench A/B) - v5-3: Mixed での段階昇格 (C6 → C5 → ...) 目標性能: Mixed 16–1024B で 50–60M ops/s (mimalloc の 5割) 🤖 Generated with Claude Code Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
130 lines
5.0 KiB
Markdown
130 lines
5.0 KiB
Markdown
# 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 で応用
|