hakmem/docs/analysis/ULTRA_MID_V3_GENERATION_SUMMARY.md

# ULTRA+MID v3 Generation Summary (2025-12-12)

## 概要

この世代（2025-12-10～12-12）で、Tiny/ULTRA 層の完成と MID v3 の本線採用により、0-1024B 範囲の性能最適化が完了しました。

## 層別状態まとめ

### 0-256B: Tiny/ULTRA（完成・凍結）

**状態**: Production (frozen)
**性能**: Mixed 16-1024B = **43.9M ops/s** (baseline 30.6M → +43.5%)

**完成内容**:
- C4-C7 ULTRA: 寄生型 TLS cache で legacy 経路を 49% → 4.8% に削減
- v3 backend: alloc_current_hit=100%, free_retire=0.1% で堅牢に
- Dispatcher/gate snapshot: ENV/route を hot path から排除
- C7 ULTRA refill: division → bit shift で +11%

**設計原則**:
- Small object (C2-C7) = ULTRA 最適化済み（fast path/slow path 共に）
- v3 backend = ロジック完全最適化（残り 5% は header write/memcpy 等の内部コスト）
- 研究箱（v4/v5）は OFF で標準プロファイルに影響なし

**詳細**: `PERF_EXEC_SUMMARY_ULTRA_PHASE_20251211.md`

---

### 257-768B: MID v3（本線採用）

**状態**: Production (mainline)
**性能**: C6-heavy = +11.1%, Mixed (257-768B) = **+19.8%**

**完成内容**:
- MID-V3-0～5: 型定義、RegionIdBox 統合、alloc/free 実装
- MID-V3-6: hakmem.c メイン経路統合（箱化モジュール化）
- Role separation: 257-768B 専用（C7 は ULTRA に任せる）
- Profile 採用: C6_HEAVY_LEGACY_POOLV1 と MIXED_TINYV3_C7_SAFE でデフォルト ON

**設計原則**:
- Lane = TLS cache, Page = authoritative freelist（二重管理回避）
- RegionIdBox: ptr→page_meta O(1) lookup（TLS cached binary search）
- Batch refill: 16 items/batch（デフォルト、ENV 調整可能）

**ENV**:
```bash
HAKMEM_PROFILE=C6_HEAVY_LEGACY_POOLV1  # または MIXED_TINYV3_C7_SAFE
# Auto-enables:
# HAKMEM_MID_V3_ENABLED=1
# HAKMEM_MID_V3_CLASSES=0x40  # C6 only
```

**詳細**: `MID_POOL_V3_DESIGN.md`

---

### 769-1024B: C7 ULTRA（完成・凍結）

**状態**: Production (frozen)
**性能**: Optimized for 1KB allocations (ULTRA 層に統合済み)

**設計原則**:
- MID v3 から意図的に除外（C7 は ULTRA が最適）
- v4/v5/v6 研究箱も C7 には適用せず、ULTRA 経路を維持

---

### V6 C6-only Headerless（研究箱、V6-HDR-4 完成）

**状態**: Research box (frozen at V6-HDR-4)
**性能**: Cost almost neutral / slight positive (~1-2%)

**完成内容**:
- V6-HDR-0～3: 型定義、RegionIdBox 統合、alloc/free headerless 実装
- V6-HDR-4: Cold refill/retire、sanity test、構造検証完了
- 設計原則: 4層 Box Theory（L0 ULTRA / L1 TLS / L2 Segment / L3 Policy）

**結論**:
- Headerless 設計の実証完了
- コストほぼ相殺〜微プラス（1-2% 程度）
- 本線採用せず、研究箱として保持（将来の参考実装）

**詳細**: `SMALL_V6_DESIGN.md`

---

## 役割分担の完成形

```
Size Range     | Allocator     | Status              | Performance
---------------|---------------|---------------------|------------------
0-256B         | Tiny/ULTRA    | Production (frozen) | +43.5% (Mixed)
257-768B       | MID v3        | Production          | +19.8% (257-768B)
769-1024B      | C7 ULTRA      | Production (frozen) | Optimized
1025B-52KB     | Pool          | Existing path       | Stable
52KB-2MB       | ACE           | Existing path       | Stable
2MB+           | Large mmap    | Existing path       | Stable
```

## 設計原則の統一

### Box Modularization Pattern

全層で統一された箱化設計：
- **Type Box**: 型定義（`*_box.h`）
- **ENV Box**: 環境変数ゲート（`*_env_box.h`）
- **Implementation**: 実装（`*.c`）
- **Cold Iface**: L1/L2 境界インターフェース（`*_cold_iface*.h`）

### RegionIdBox Integration

全層で統合された ptr→meta lookup：
- Tiny/ULTRA: REGION_KIND_SMALL_V6 / REGION_KIND_C7_ULTRA
- MID v3: REGION_KIND_MID_V3
- v6: REGION_KIND_SMALL_V6（headerless）
- TLS cached binary search で O(1) lookup

### ENV-Controlled Routing

研究箱は明示 opt-in：
- v4/v5: `HAKMEM_SMALL_HEAP_V[4|5]_ENABLED=1` + `HAKMEM_SMALL_HEAP_V[4|5]_CLASSES=0x??`
- v6: `HAKMEM_SMALL_HEAP_V6_ENABLED=1` + `HAKMEM_SMALL_HEAP_V6_CLASSES=0x40`
- MID v3: `HAKMEM_MID_V3_ENABLED=1` + `HAKMEM_MID_V3_CLASSES=0x40`（本線では Profile 経由で自動）

---

## 本線プロファイル構成（2025-12-12 現在）

### MIXED_TINYV3_C7_SAFE（標準 Mixed 16-1024B）

```bash
HAKMEM_PROFILE=MIXED_TINYV3_C7_SAFE
# Auto-enables:
# - Tiny/ULTRA (C7_SAFE profile)
# - MID v3 (257-768B, C6 only)
# - SmallObject v3 (C7-only backend)
# - Tiny front v3 + LUT + fast classify
# - v4/v5/v6 OFF (研究箱)
```

**期待性能**: 42-44M ops/s (Mixed 16-1024B, 1M iter, ws=400)

### C6_HEAVY_LEGACY_POOLV1（C6-heavy 257-768B）

```bash
HAKMEM_PROFILE=C6_HEAVY_LEGACY_POOLV1
# Auto-enables:
# - Tiny/ULTRA (C7_SAFE profile)
# - MID v3 (257-768B, C6 only)
# - SmallObject v3 (C7-only backend)
# - Pool v1 (flatten OFF)
# - v4/v5/v6 OFF (研究箱)
```

**期待性能**: 22-23M ops/s (C6-heavy 257-768B, 1M iter, ws=400)

---

## 次世代テーマ候補

### Option A: 小さめテーマ（+数％狙い）

**so_alloc/so_free 枝削り**:
- 現状の v3 backend で残っている条件分岐を削減
- alloc_current_hit=100% だが、内部に header write/check が残存
- 狙い: +1-3% 程度の微改善

**メリット**: 安全、既存設計の洗練
**デメリット**: 大きなジャンプはない

### Option B: 次世代テーマ（大きめ変更）

**MID/Pool v3 拡張**:
- 現在 257-768B (C6 only) を C5 (128B) や C4 (64B) に拡張
- 狙い: 128-256B 範囲の改善（現在 Tiny/ULTRA が最適だが、さらなる実験）

**C2/C3 ULTRA 実験**:
- 16-64B 範囲に ULTRA 適用（現在 legacy 経路が主流）
- 狙い: 小サイズでも ULTRA の恩恵を受ける

**メリット**: 新しい最適化領域の開拓
**デメリット**: 既存の安定領域に影響する可能性

---

## まとめ

### この世代で達成したこと

1. **Tiny/ULTRA 完成**: 0-256B で +43.5% (Mixed)、設計凍結
2. **MID v3 本線採用**: 257-768B で +19.8%、Profile デフォルト ON
3. **C7 ULTRA 凍結**: 769-1024B で最適化完了
4. **v6 研究箱完成**: C6-only headerless 実証（V6-HDR-4）

### 設計的な完成度

- **役割分担**: 各サイズ範囲に最適化された allocator が明確
- **Box 化**: 全層で統一された箱化設計
- **RegionIdBox**: 全層で統合された ptr→meta lookup
- **ENV 制御**: 研究箱は明示 opt-in、本線は Profile 経由で安定

### この世代の「形」

0-1024B の性能最適化が完了し、役割分担が明確になりました。この構成を「固定」として、次世代テーマは：
- 既存設計の洗練（枝削り）
- 新しい最適化領域の開拓（拡張実験）

のいずれかから選択できます。

---

**作成日**: 2025-12-12
**関連ドキュメント**:
- `PERF_EXEC_SUMMARY_ULTRA_PHASE_20251211.md`
- `MID_POOL_V3_DESIGN.md`
- `SMALL_V6_DESIGN.md`
- `ENV_PROFILE_PRESETS.md`
- `CURRENT_TASK.md`