hakmem/docs/analysis/HAKMEM_V2_GENERATION_SUMMARY.md

HAKMEM v2 世代 総括（第1章完）

1. 位置づけ

HAKMEM v2 世代は、ChatGPT Pro の層設計に基づく「芯から作り直す」実装練習として開始。 L0（ULTRA）から L3（Policy）までの層構造を確立し、Box Theory に沿った実装パターンを確立した。

Phase v7-4（Policy Box 導入）をもって、v2 世代は設計上の完成を見た。

2. アーキテクチャ層構造

L0: ULTRA（C4-C7, FROZEN 世代）

特性:

• C7: 2MiB Segment + 64KiB Page + TLS freelist
• C4-C6: ULTRA-free / ULTRA-alloc (寄生型 TLS cache)
• Status: FROZEN（完成度高、これ以上改善不要）

性能:

• C7 phase 1a/1b: +11% 改善（division → bit shift 最適化完了）
• Mixed 16-1024B に貢献: +11% baseline 達成

L1: SmallObject 新世代（v7 / MID v3 / Legacy）

L1-a: SmallObject v7（C6-only 研究箱）

狙い: small～mid を 1 個の SmallHeapCtx + Segment で扱う土台作り

実装状況:

• Phase v7-2: C6-only 本実装完了（refill/retire 動作確認）
• Phase v7-3: TLS segment fast path 最適化（overhead -7.0% → -4.3%）
• Phase v7-4: Policy Box 統合（route 決定一元化）

性能:

• C6-only (400-510B, 500K iter):
  • Legacy baseline: 58.6M ops/s
  • v7 Phase v7-2: 54.5M ops/s (-7.0%)
  • v7 Phase v7-3: 56.3M ops/s (-4.3%)
• 改善トレンド: 38% overhead 削減済み

設計完了事項:

• SmallSegment_v7: 2MiB segment, free page stack
• SmallHeapCtx_v7: TLS context, TLS segment hints (v7-3)
• ColdIface_v7: page refill/retire
• RegionIdBox: v7 segment registration + fast lookup

残課題:

• -4.3% overhead → ±0% へ（multi-class 拡張で分摊予定）
• C5/C4 対応（Phase v7-5 候補）

L1-b: MID v3（257-768B 本線）

特性: Specialized TLS heap for mid-size allocations Status: Stable, production-ready 担当: C5-C6 (mixed workload では ULTRA / v7 と共存)

L1-c: Legacy（TinyHeap v1 / Pool v1）

特性: Fallback for unhandled classes Status: Stable, production baseline

L2: Infrastructure（Segment / RegionId / ColdIface）

Segment:

• SmallSegment_v6: V6 headerless core 用（64KiB page, free stack）
• SmallSegment_v7: v7 core 用（2MiB segment, same geometry）
• 型パターン統一により、将来の multi-class 拡張が容易

RegionIdBox:

• v6/v7 segment の ptr → region lookup（O(log N) binary search）
• TLS cache で high-hit-rate workload を最適化
• Phase v7-3 で TLS fast path により overhead 削減

ColdIface:

• v6: small_cold_v6_refill_page / retire_page
• v7: small_cold_v7_refill_page / retire_page
• API 統一により multi-segment 拡張も設計可能

L3: Policy & Stats（Route 決定・統計）

Policy Box (Phase v7-4 新規):

• SmallPolicyV7: route_kind[8] で C0-C7 の route 一括決定
• Priority (固定): ULTRA > v7 > MID_v3 > LEGACY
• ENV 一元化: init_from_env で全 ENV を一度だけ解釈

Frontend との関係:

• Front: size → class_idx → policy->route_kind[ci] → switch
• Front は ENV を直接読まない（policy に委譲）
• 設定変更は Policy Box だけで完結

Stats (将来):

• SmallPageStatsV7: page retire 時に publish
• PolicyLearner（v7-5 候補）: stats から最適 route を学習

3. サイズ帯の担当整理

サイズ	Class	Primary	Secondary	Status
1KB	C7	ULTRA	-	FROZEN
512B	C6	v7 / MID_v3	ULTRA	Research
256B	C5	MID_v3	ULTRA	Stable
128B	C4	ULTRA	MID_v3	Partial
64B	C3	Legacy	-	Fallback
32B	C2	Legacy	-	Fallback
16B	C1	Legacy	-	Fallback
8B	C0	Legacy	-	Fallback

4. 最適化達成状況

Throughput

• Baseline (no optimization): 39.5M ops/s (Mixed 16-1024B)
• Phase 1a (division → shift): 39.5M ops/s (±0%)
• Phase 1b (segment learning 削除): 42.3M ops/s (+7.1%)
• Final (v7-3 + Policy Box): 43-44M ops/s (+11.1% 実測)

Overhead Reduction

• v7 Phase v7-2: -7.0% (RegionIdBox binary search cost)
• v7 Phase v7-3: -4.3% (TLS fast path optimization)
• Improvement: 38% overhead削減

Architectural Wins

• ✅ Layer structure (L0-L3) 明確化
• ✅ Box Theory 実装パターン確立
• ✅ Policy Box で ENV 一元化
• ✅ Segment/RegionId 型パターン統一

5. Box Theory 実装パターン（v2 で確立）

各層の責務:

L0: ULTRA
  └─ 最高速アロケータ（size class 専用）

L1: HotBox (v7/MID/Legacy)
  └─ TLS cache + current/partial page 管理

L2: ColdIface + Segment + RegionId
  └─ Page lifecycle (refill/retire) + segment管理 + region lookup

L3: Policy Box + Stats + Learner (将来)
  └─ Route決定・env管理・統計・学習

特徴:

• 各層が内部完結（下の層に依存しない API）
• ENV は L3 だけで読む（L1-L0 は ENV-free）
• TLS cache はレイヤーごとに独立
• Future: Learner で L3 ← stats をフィードバック

6. 次世代 v7 への橋渡し（設計メモ）

v7 第2章の候補

6-1. Multi-class 拡張（C5/C4 対応）

狙い: -4.3% overhead を複数クラスで分摊して ±0% へ

設計考察:

• SmallSegment_v7 を class ごとに独立 (C6/C5/C4 各segment)
• または: 複数 class を 1 segment 内で共存
• TLS segment hint が複数class対応可能か検証

実装レベル:

• SmallHeapCtx_v7.tls_seg_base/end は 1 segment 前提
• Multi-segment 対応なら: tls_seg_list[] or segment registry
• 既存 RegionIdBox で OK（拡張不要）

6-2. Learner 連携（動的 route 選択）

狙い: 実行時統計で v7 / MID_v3 の最適 route を自動選択

設計考察:

• SmallPageStatsV7 publish → PolicyLearner ingestion
• Learner から Policy Box へ route_kind[] 更新
• 学習率・履歴長・信頼度 threshold は TBD

実装レベル:

• Policy Box snapshot は read-only
• 更新は small_policy_v7_update_from_learner() 経由
• Thread-safe update (maybe atomic or RCU)

6-3. HeaderLess 統一（v7/v6 の mode 統合）

狙い: RegionId lookup で headerless を完全活用

設計考察:

• v7 でも header を書かない mode の検証
• Free 時に page_meta から class_idx を取得
• Small allocation では header mismatch のリスク軽減

実装レベル:

• SmallPageMeta にはすでに class_idx あり
• Free path: hint 無視して page->class_idx 信頼
• Validation: class_idx 範囲チェックだけ

次世代開始の条件

• v7 が ±0% overhead 達成（multi-class 拡張）
• または HakORune / JoinIR 一段落後に再開
• v2 設計ドキュメントが凍結状態で読み返せること

7. 凍結方針

v2 世代はここで一旦完成とする。

凍結対象:

• ULTRA (C4-C7): 改造禁止（FROZEN）
• MID v3: バグ修正のみ（拡張禁止）
• v7 (C6-only): 設計確定、性能改善研究中（code freeze）
• Policy Box: route 決定一元化完了

HakORune / JoinIR優先:

• HAKMEM は凍結
• 次世代 v7 再開は JoinIR ノーマライズ一段落後

再開条件:

• この総括ドキュメントが地図として機能すること
• v7-4 の設計メモ (6-1/6-2/6-3) が実装ガイド足り得ること

8. 謝辞・振り返り

この v2 世代を通じて以下を学んだ/確立した:

• Box Theory の実装パターン（L0-L3 層分離）
• ENV 一元化の必要性（Policy Box）
• TLS cache の効果（segment fast hint, page cache）
• Multi-layer allocation の複雑性と取り組み方

「芯から作り直す」というゴールに向けて、設計練習としては十分成功。 次の v7 第2章（multi-class）は、ここの学びを足がかりに進める。

---

Document Date: 2025-12-12 Final Commit: Phase v7-4 Policy Box 導入 Next Phase: v7-5 (Multi-class expansion) / HakORune priority