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（C5/C6 専用研究箱）

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

位置づけ（Phase v10 確定）:

• 基準線: Mixed 本線では HAKMEM_SMALL_HEAP_V7_ENABLED=0 (OFF)
• 用途: C5/C6 ベンチマーク専用プリセット（Learner ON）
• Status: 研究実装（設計パターン確立済み）

実装状況:

• 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 決定一元化）
• Phase v7-5b: C5 対応（256B blocks）
• Phase v7-7: Learner 統合（動的ルート切り替え）
• Phase v10: Learner デフォルト ON、v3/v4/v5 削除

性能（最新）:

• C6-only (400-510B, 500K iter):
  • Legacy baseline: 58.6M ops/s
  • v7 Phase v7-3: 56.3M ops/s (-4.3%)
• C5/C6 mixed (200-500B, 300K iter):
  • v7 + Learner: 38.7M ops/s (+127% vs Legacy)
  • Learner route switch: C5 ratio 28% < threshold 30% → MID_v3

設計完了事項:

• 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
• SmallPolicyV7: route 決定一元化
• SmallLearnerV7: 動的ワークロード検出

C5/C6 プリセット（ドキュメント参照）:

# C5/C6 ベンチマーク用（Learner ON）
HAKMEM_SMALL_HEAP_V7_ENABLED=1 \
HAKMEM_SMALL_HEAP_V7_CLASSES=0x60 \
./bench_random_mixed_hakmem 300000 400 1

残課題:

• Mixed 本線性能との差分解消（v3 backend 最適化、headerless v6 拡張）

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. サイズ帯の担当整理（Phase v10 確定）

サイズ	Class	Mixed 本線	C5/C6 専用	Status
1KB	C7	ULTRA	ULTRA	FROZEN
512B	C6	MID_v3	v7+Learner	Research preset
256B	C5	MID_v3	v7+Learner	Research preset
128B	C4	ULTRA	ULTRA	Stable
64B	C3	Legacy	Legacy	Fallback
32B	C2	Legacy	Legacy	Fallback
16B	C1	Legacy	Legacy	Fallback
8B	C0	Legacy	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 / v3 への橋渡し（設計メモ）

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 拡張）
• v3 / v7 コアの SPEC がこの総括＋各 DESIGN ドキュメントから一貫して読み取れること

7. v2 世代の位置づけ

v2 世代はここで一旦「第1章の完成版」とする。

扱い方:

• ULTRA (C4-C7): 大きな構造変更はせず、第2世代でも L0 の完成箱として前提にする。
• MID v3: 257–768B 帯の本線箱として維持しつつ、将来 v7/mid コアに統合する際の比較対象・退避先として使う。
• v7 (C6-only): 設計・実装パターンは確立済みの研究箱として残し、第2世代の v7/mid コアを作るときの参照実装にする。
• Policy Box: route 決定の一元化パターンとして、そのまま v3 世代でも使い続ける。

この総括は「ここまでが第1世代で、ここから先は v3 / v7 世代でさらに芯を削る」というための地図として扱う。

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