diff --git a/CURRENT_TASK.md b/CURRENT_TASK.md index f0cec7cf..bcdd1586 100644 --- a/CURRENT_TASK.md +++ b/CURRENT_TASK.md @@ -1782,3 +1782,41 @@ gcc -o bench_tiny_hot_hakmem ... core/smallobject_policy_v7.o ... -lm -lpthread 2. **Learner 連携**: ENV defaults + runtime learning override 3. **クラスごとの柔軟な優先順位**: ENV で ULTRA vs v7 の順序を逆転可能に 4. **Multi-class v7**: C5/C4 追加 → coverage 拡大 + +======================================================================== +## SECTION: HAKMEM v2 世代 完了宣言(第1章) +======================================================================== + +### Phase v7-4 完了時点での総括 + +Policy Box 導入により、L0-L3 の層構造が確立。 +「芯の設計練習」は達成し、v2 世代は一旦完成。 + +### 成果ハイライト + +| フェーズ | 目標 | 達成度 | +|---------|------|--------| +| ULTRA (C7) | +10% 目標 | ✅ +11% 達成 | +| MID v3 | 257-768B 本線化 | ✅ 完了 | +| v7 (C6-only) | 研究箱構築 | ✅ 完了、-4.3% overhead | +| Policy Box | route 一元化 | ✅ 完了、ENV 集約 | + +### 次世代への課題一覧 + +**v7 第2章(Phase v7-5 候補)**: +1. Multi-class 拡張(C5/C4)→ overhead 分摊 +2. Learner 連携 → 動的 route 選択 +3. HeaderLess 統一 → v6/v7 mode 統合 + +**開発再開条件**: +- HakORune / JoinIR ノーマライズ優先 +- v2 世代ドキュメント(HAKMEM_V2_GENERATION_SUMMARY.md)が凍結状態で読み返せること + +### 凍結方針 + +- ULTRA: 改造禁止(FROZEN) +- MID v3: バグ修正のみ +- v7: code freeze(research boxとして保存) +- HAKMEM: ここで一旦完成 + +次の開発は HakORune / JoinIR 優先。 diff --git a/docs/analysis/HAKMEM_V2_GENERATION_SUMMARY.md b/docs/analysis/HAKMEM_V2_GENERATION_SUMMARY.md new file mode 100644 index 00000000..35cee665 --- /dev/null +++ b/docs/analysis/HAKMEM_V2_GENERATION_SUMMARY.md @@ -0,0 +1,236 @@ +# 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 diff --git a/docs/analysis/SMALLOBJECT_V7_DESIGN.md b/docs/analysis/SMALLOBJECT_V7_DESIGN.md index de8cd1ba..33923a07 100644 --- a/docs/analysis/SMALLOBJECT_V7_DESIGN.md +++ b/docs/analysis/SMALLOBJECT_V7_DESIGN.md @@ -388,3 +388,75 @@ ULTRA/MID_v3/LEGACY は既存の `tiny_route_env_box.h` を併用(後で統合 --- + +## 8. v7 第2章への設計メモ(Phase v7-4 完了時点) + +### 現状(C6-only 研究箱) + +- **性能**: 56.3M ops/s (Phase v7-3, -4.3% overhead) +- **設計完了**: SmallHeapCtx / Segment / ColdIface / RegionIdBox 統一 +- **Policy統合**: 完了(route 一元化) + +### -4.3% Overhead の内訳(仮説) + +| 要因 | 推定 | 対策 | +|------|------|------| +| Page metadata 間接参照 | ~2% | Multi-class で分摊 | +| Extra validation | ~1% | Branch優化 | +| RegionIdBox fallback | ~1% | TLS cache強化 | + +### Multi-class 拡張時の検討項目 + +1. **Segment 設計**: + - Option A: Class ごとに独立 segment (SmallSegment_v7_C6, v7_C5, ...) + - Option B: 複数 class を 1 segment 内で共存 + - Decision point: TLS hint の複数 segment 対応 + +2. **TLS Context 拡張**: + ```c + typedef struct SmallHeapCtx_v7_multi { + SmallClassHeap_v7 cls[8]; + // Multi-class TLS hints + struct { + uintptr_t seg_base; + uintptr_t seg_end; + SmallSegment_v7* seg; + } tls_seg[5]; // C3-C7 + } SmallHeapCtx_v7_multi; + ``` + +3. **Overhead 分摊の期待値**: + - C6-only: -4.3% (current) + - C5+C6: -2% (overhead 薄まる) + - C4+C5+C6: -1% (さらに薄まる) + +### Learner 連携(Phase v7-5 候補) + +**概要**: SmallPageStatsV7 から実行時最適 route を学習 + +```c +// Policy Box update interface +void small_policy_v7_update_from_learner( + const SmallLearnerStats* stats, + SmallPolicyV7* policy_out +); +``` + +**学習要件**: +- Alloc/free count, peak_live, lifetime_ms +- v7 vs MID_v3 の速度比較 +- Learner の信頼度 threshold + +### HeaderLess 統一(将来検討) + +v7-5 以降でも header を削除できるかの検証: +- v6 headerless: page->class_idx で header-free を実装済み +- v7 適用: free 時に page_meta から class_idx を取得 +- Benefit: 1 byte 削減 per allocation(micro, 但し alloc density up) + +### 次世代開始チェックリスト + +- [ ] HAKMEM_V2_GENERATION_SUMMARY.md が地図として機能 +- [ ] v7-4 時点の設計メモ (本セクション) が読み返せる +- [ ] HakORune / JoinIR が一段落(or 並行可能に) +- [ ] v7 research box は冷凍庫に保存完了