79674c9390
Removal strategy: Deprecate routes by disabling ENV-based routing - v3/v4/v5 enum types kept for binary compatibility - small_heap_v3/v4/v5_enabled() always return 0 - small_heap_v3/v4/v5_class_enabled() always return 0 - Any v3/v4/v5 ENVs are silently ignored, routes to LEGACY Changes: - core/box/smallobject_hotbox_v3_env_box.h: stub functions - core/box/smallobject_hotbox_v4_env_box.h: stub functions - core/box/smallobject_v5_env_box.h: stub functions - core/front/malloc_tiny_fast.h: remove alloc/free cases (20+ lines) Benefits: - Cleaner routing logic (v6/v7 only for SmallObject) - 20+ lines deleted from hot path validation - No behavioral change (routes were rarely used) Performance: No regression expected (v3/v4/v5 already disabled by default) Next: Set Learner v7 default ON, production testing 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
369 lines
22 KiB
Markdown
369 lines
22 KiB
Markdown
# AGENTS: 箱理論（Box Theory）設計ガイドライン
|
||
|
||
本リポジトリでは、変更・最適化・デバッグを一貫して「箱理論（Box Theory）」で進めます。すべてを“箱”で分け、境界で接続し、いつでも戻せるように積み上げることで、複雑性を抑えつつ失敗コストを最小化します。
|
||
|
||
---
|
||
|
||
## 何が効くのか（実績）
|
||
|
||
- ❌ Rust/inkwell: 複雑なライフタイム管理
|
||
↓
|
||
- ✅ 箱理論適用: 650行 → 100行（SSA構築）
|
||
|
||
なぜ効果があるか:
|
||
- PHI/Block/Value を「箱」として扱い、境界（変換点）を1箇所に集約
|
||
- 複雑な依存関係を箱の境界で切ることで単体検証が容易
|
||
- シンプルな Python/llvmlite で 2000行で完結（道具に依存せず“箱”で分割して繋ぐ）
|
||
|
||
補足（C 実装時の利点）
|
||
- C の場合は `static inline` により箱間のオーバーヘッドをゼロに近づけられる（インライン展開）
|
||
|
||
---
|
||
|
||
## 🎯 AI協働での合言葉（5原則）
|
||
|
||
1. 「箱にする」: 設定・状態・橋渡しは Box 化
|
||
- 例: TLS 状態、SuperSlab adopt、remote queue などは役割ごとに箱を分離
|
||
2. 「境界を作る」: 変換は境界1箇所で
|
||
- 例: adopt → bind、remote → freelist 統合、owner 移譲などの変換点を関数1箇所に集約
|
||
3. 「戻せる」: フラグ・feature で切替可能に
|
||
- `#ifdef FEATURE_X` / 環境変数 で新旧経路を A/B 可能に（回帰や切り戻しを即時化）
|
||
4. 「見える化」: ダンプ/JSON/DOT で可視化
|
||
- 1回だけのワンショットログ、統計カウンタで“芯”を掴む（常時ログは避ける）
|
||
5. 「Fail-Fast」: エラー隠さず即座に失敗
|
||
- ENOMEM/整合性違反は早期に露呈させる（安易なフォールバックで隠さない）
|
||
|
||
要するに: 「すべてを箱で分けて、いつでも戻せるように積み上げる」設計哲学にゃ😺🎁
|
||
|
||
---
|
||
|
||
## 適用ガイド（このリポジトリ）
|
||
|
||
- 小さく積む（Box 化）
|
||
- Remote Free Queue, Partial SS Adopt, TLS Bind/Unbind を独立した“箱”として定義
|
||
- 箱の API は最小・明確（init/publish/adopt/drain/bind など）
|
||
|
||
- 参照してほしい設計ドキュメント
|
||
- `HAKMEM_V2_GENERATION_SUMMARY.md`（ULTRA + MID v3 + v6/v7 研究箱までの“第1章”まとめ）
|
||
- `docs/analysis/SMALLOBJECT_V7_DESIGN.md`（SmallObject v7 / HAKMEM v3 コアの層構造と箱割り）
|
||
- `docs/analysis/V7_ARCHITECTURE_DECISION_MATRIX.md`（v7 世代の設計オプションと意思決定マトリクス）
|
||
|
||
- 境界は1箇所
|
||
- Superslab 再利用の境界は `superslab_refill()` に集約（publish/adopt の接点）
|
||
- Free の境界は “same-thread / cross-thread” の判定1回
|
||
|
||
- 切替可能（戻せる）
|
||
- 新経路は `#ifdef` / 環境変数でオンオフ（A/B と回帰容易化）
|
||
- 例: `HAKMEM_TINY_PHASE6_ULTRA_SIMPLE`、`HAKMEM_DEBUG_VERBOSE`、`HAKMEM_TINY_*` env
|
||
|
||
- 見える化（最小限）
|
||
- 1回だけのデバッグ出力（ワンショット）と統計カウンタで芯を掴む
|
||
- 例: [SS OOM]、[SS REFILL] のワンショットログ、alloc/freed/bytes の瞬間値
|
||
|
||
- Fail-Fast
|
||
- ENOMEM・整合性違反はマスクせず露出。フォールバックは“停止しないための最後の手段”に限定
|
||
|
||
- 運用ルール（Pool flatten）
|
||
- Pool v1 flatten / Zero Mode は LEGACY mid/smallmid ベンチ専用の箱。C7_SAFE プロファイルでは flatten を触らない（安定性優先のため常時 OFF）。
|
||
|
||
---
|
||
|
||
## 実装規約（C向けの具体）
|
||
|
||
- `static inline` を多用し箱間の呼び出しをゼロコスト化
|
||
- 共有状態は `_Atomic` で明示、CAS ループは局所化（MPSC push/pop はユーティリティ化）
|
||
- 競合制御は「箱の内側」に閉じ込め、外側はシンプルに保つ
|
||
- 1つの箱に 1つの責務（publish/adopt、drain、bind、owner 移譲 など）
|
||
|
||
---
|
||
|
||
## チェックリスト（PR/レビュー時）
|
||
|
||
- 箱の境界は明確か（変換点が1箇所に集約されているか）
|
||
- フラグで戻せるか（A/B が即時に可能か）
|
||
- 可視化のフックは最小か（ワンショット or カウンタ）
|
||
- Fail-Fast になっているか（誤魔化しのフォールバックを入れていないか）
|
||
- C では `static inline` でオーバーヘッドを消しているか
|
||
|
||
---
|
||
|
||
この AGENTS.md は、箱理論の適用・コーディング・デバッグ・A/B 評価の“共通言語”です。新しい最適化や経路を足す前に、まず箱と境界を設計してから手を動かしましょう。
|
||
|
||
---
|
||
|
||
## Learning Layer（ACE / ELO / Learner）の箱化ポリシー
|
||
|
||
ACE/ELO/CAP Learner などの「学習する機能」も、Tiny や Superslab と同様に Box として扱います。
|
||
ホットパスを汚さず、いつでも FROZEN/OFF に戻せるようにすることが原則です。
|
||
|
||
- 学習は上層の箱に閉じ込める
|
||
- L0 Tiny / L1 Superslab / TLS SLL / Remote Queue は **学習ロジックを持たない**。
|
||
- ELO / ACE Controller / CAP Learner は「ポリシー箱」として、ノブやしきい値だけを更新する。
|
||
- ホットパス側は「現在のポリシー値」を読むだけにし、学習の有無を意識しない。
|
||
|
||
- FROZEN / LEARN / OBSERVE を明確に分ける
|
||
- FROZEN: 学習 OFF。固定ポリシーのみ使用（デフォルト運用）。
|
||
- LEARN: バックグラウンドでポリシー更新を行う（ベンチ / 研究用）。
|
||
- OBSERVE: Tiny などの下層の箱を「観測だけ」するモード（動作は変えない）。
|
||
- モード切り替えは `HAKMEM_MODE` / `HAKMEM_ACE_ENABLED` / `HAKMEM_LEARN` 等の ENV から行い、いつでも戻せるようにする。
|
||
|
||
- ドキュメントと設計の窓口
|
||
- 学習レイヤ全体の構造と責務は `docs/analysis/LEARNING_LAYER_OVERVIEW.md` にまとめる。
|
||
- 各学習 Box（ELO / ACE Controller / CAP Learner）の詳細仕様や A/B 結果は、docs/analysis / docs/benchmarks / docs/paper 配下に箱ごとに整理する。
|
||
- AGENTS.md では「学習は必ず別箱」「ホットパスを汚さない」「ENV で切り戻せる」というルールだけを守る。
|
||
|
||
|
||
---
|
||
|
||
## 研究箱ポリシー: SmallObject v6（Headerless 設計検証）
|
||
|
||
SmallObject v6（C6-only headerless allocation）は、「header elimination の実現可能性」を実証する**研究箱**です。以下のルールで管理します。
|
||
|
||
### v6 の現在地
|
||
|
||
- **状態**: 凍結（デフォルト OFF、ENV opt-in の研究用）
|
||
- **性能**: baseline ±数% で相当 = 基本的な設計目標は達成
|
||
- **設計成果**:
|
||
- RegionIdBox が薄く保たれた（ptr 分類のみ）
|
||
- TLS-scope segment registration + same-page cache で lookup overhead を軽減
|
||
- Headerless allocation が実装可能なことを実証
|
||
|
||
### 凍結後の方針
|
||
|
||
1. **コード保持**: v6 実装コードは削除しない。参考設計として保持。
|
||
2. **デフォルト OFF**: デフォルトプロファイルには一切関与しない。
|
||
3. **研究用のみ**: ENV 環境変数 `HAKMEM_SMALL_HEAP_V6_*` で明示的に有効化する場合のみ動作。
|
||
4. **今後のリソース**: v6 の P2/P3 最適化は後回しに。mid/pool v3 による C6-heavy 本格改善に注力する。
|
||
5. **ドキュメント**: SmallObject v6 の詳細は `docs/analysis/SMALLOBJECT_CORE_V6_DESIGN.md` に集約。CURRENT_TASK.md は概要のみ。
|
||
|
||
### 凍結をすり抜ける条件
|
||
|
||
v6 に手を入れるのは以下の場合に限定：
|
||
- クリティカルなバグ修正（deadlock / segfault）
|
||
- 基盤（TLS 登録、segment allocation）に関わる変更の伝播
|
||
- 「mid/pool v3 で成功した パターンを v6 にも適用」といった、mid と v6 の共通化
|
||
|
||
---
|
||
|
||
## Tiny 向け「積み方 v2」(層を下から固める)
|
||
|
||
下層の箱が壊れている状態で上層を積むと必ず崩れます。まず下から順に箱を“堅牢化”してから上を載せる、を徹底します。
|
||
|
||
層と責務
|
||
- Box 1: Atomic Ops (最下層)
|
||
- 役割: `stdatomic.h` による CAS/Exchange の秩序付け（Acquire/Release）。
|
||
- ルール: メモリ順序を箱内で完結させる（外側に弱い順序を漏らさない）。
|
||
|
||
- Box 2: Remote Queue (下層)
|
||
- 役割: cross-thread free の MPSC スタック（push/exchange）とカウント管理。
|
||
- API: `ss_remote_push(ss, slab_idx, ptr) -> transitioned(0/1)`、`ss_remote_drain_to_freelist(ss, slab_idx)`、`ss_remote_drain_light(ss)`
|
||
- 不変条件 (Invariants):
|
||
- push はノードの next を書き換える以外に副作用を持たない（freelist/owner へは触れない）。
|
||
- head は SuperSlab 範囲内（Fail-Fast 範囲検証）。
|
||
- `remote_counts[s]` は push/drain で単調に整合する（drain 後は 0）。
|
||
- 境界: freelist への統合は必ず drain 関数内（1 箇所）。publish/adopt からの直接 drain は禁止。
|
||
|
||
- Box 3: Ownership (中層)
|
||
- 役割: slab の所有者遷移（`owner_tid`）。
|
||
- API: `ss_owner_try_acquire(meta, tid) -> bool`（`owner_tid==0` の時のみ CAS で取得）、`ss_owner_release(meta, tid)`、`ss_owner_is_mine(meta, tid)`
|
||
- 不変条件:
|
||
- Remote Queue は owner に触らない（Box 2→3 への侵入禁止）。
|
||
- Acquire 成功後のみ “同一スレッド” の高速経路を使用する。
|
||
- 境界: bind 時にのみ acquire/release を行う（採用境界 1 箇所）。
|
||
|
||
- Box 4: Publish / Adopt (上層)
|
||
- 役割: 供給の提示（publish）と消費（adopt）。
|
||
- API: `tiny_publish_notify(class, ss, slab)` → `tiny_mailbox_publish()`、`tiny_mailbox_fetch()`、`ss_partial_publish()`、`ss_partial_adopt()`
|
||
- 不変条件:
|
||
- publish は “通知とヒント” のみ（freelist/remote/owner に触れない）。
|
||
- `ss_partial_publish()` は unsafe drain をしない。必要なら drain は採用側境界で実施。
|
||
- publish 時に `owner_tid=0` を設定してもよいが、実際の acquire は採用境界でのみ行う。
|
||
- 境界: adopt 成功直後にだけ `drain → bind → owner_acquire` を行う（順序は必ずこの 1 箇所）。
|
||
|
||
実装ガイド（境界の 1 か所化）
|
||
- Refill 経路（`superslab_refill()` / `tiny_refill_try_fast()`）でのみ:
|
||
1) sticky/hot/bench/mailbox/reg を “peek して” 候補を得る
|
||
2) 候補が見つかったら当該 slab で `ss_remote_drain_to_freelist()` を 1 回だけ実行（必要時）
|
||
3) freelist が非空であれば `tiny_tls_bind_slab()` → `ss_owner_try_acquire()` の順で確定
|
||
4) 確定後にのみ publish/overflow は扱う（不要な再 publish/drain はしない）
|
||
|
||
Do / Don’t（壊れやすいパターンの禁止）
|
||
- Don’t: Remote Queue から publish を直接呼ばない条件分岐を増やす（通知の濫用）。
|
||
- Don’t: publish 側で drain / owner をいじる。
|
||
- Do: Remote Queue は push と count 更新のみ。publish は通知のみ。採用境界で drain/bind/owner を一度に行う。
|
||
|
||
デバッグ・トリアージ順序（Fail‑Fast）
|
||
1) Box 2（Remote）単体: push→drain→freelist の整合をアサート（範囲検証 ON, `remote_counts` 符合）。
|
||
2) Box 3（Ownership）単体: `owner_tid==0` からの acquire/release を並行で連続試験。
|
||
3) Box 4（Publish/Adopt）単体: publish→mailbox_register/fetch の通電（fetch ヒット時のみ adopt を許可）。
|
||
4) 全体: adopt 境界でのみ `drain→bind→owner_acquire` を踏んでいるかリングで確認。
|
||
|
||
可視化と安全化（最小構成）
|
||
- Tiny Ring: `TINY_RING_EVENT_REMOTE_PUSH/REMOTE_DRAIN/MAILBOX_PUBLISH/MAILBOX_FETCH/BIND` を採用境界前後に記録。
|
||
- Env（A/B・切戻し）:
|
||
- `HAKMEM_TINY_SS_ADOPT=1/0`（publish/adopt 全体の ON/OFF）
|
||
- `HAKMEM_TINY_RF_FORCE_NOTIFY=1`（初回通知の見逃し検出）
|
||
- `HAKMEM_TINY_MAILBOX_SLOWDISC(_PERIOD)`（遅延登録の発見）
|
||
- `HAKMEM_TINY_MUST_ADOPT=1`（mmap 直前の採用ゲート）
|
||
|
||
最小テスト（箱単位の smoke）
|
||
- Remote Queue: 同一 slab へ N 回 `ss_remote_push()` → `ss_remote_drain_to_freelist()` → `remote_counts==0` と freelist 長の一致。
|
||
- Ownership: 複数スレッドで `ss_owner_try_acquire()` の成功が 1 本だけになること、`release` 後に再取得可能。
|
||
- Publish/Mailbox: `tiny_mailbox_publish()`→`tiny_mailbox_fetch()` のヒットを 1 回保証。`fetch_null` のとき `used` 拡張が有効。
|
||
|
||
運用の心得
|
||
- 下層（Remote/Ownership）に疑義がある間は、上層（Publish/Adopt）を “無理に” 積み増さない。
|
||
- 変更は常に A/B ガード付きで導入し、SIGUSR2/リングとワンショットログで芯を掴んでから上に進む。
|
||
|
||
---
|
||
|
||
## 健康診断ランと注意事項（Superslab / madvise / Pool 用）
|
||
|
||
このリポジトリは Superslab / madvise / Pool v1 flatten など OS 依存の経路を多用します。
|
||
「いつの間にか壊れていた」を防ぐために、次の“健康診断ラン”と注意事項を守ってください。
|
||
|
||
※ 開発マシンと OS 環境は、基本的にセッションを通じて同一構成（同一ハードウェア・同一カーネル設定）を維持して運用しています。性能の変化は「コード差分」か「明示的に変更した ENV」の影響として扱い、マシン側の揺らぎで説明しない方針です。
|
||
|
||
- Perf / ベンチ計測の原則
|
||
- ホットパス（Tiny front / SmallObject v3/v4 / Pool / Superslab）に手を入れるときは、必ず **変更前と変更後で同じプロファイルのベンチと perf** を 1 本ずつ取ってから評価すること（「perf を見ずに最適化しない」）。
|
||
- Mixed 16–1024B は `HAKMEM_PROFILE=MIXED_TINYV3_C7_SAFE`、mid/smallmid は `HAKMEM_PROFILE=C6_HEAVY_LEGACY_POOLV1` を基準とし、A/B は原則この 2 本で行う。
|
||
- 新しい箱を追加したら、CURRENT_TASK.md / docs/analysis 配下に A/B の ops/s と主要 self% を必ずメモしてから次の箱に進む。
|
||
|
||
- DSO 領域には触らない（Superslab OS Box のフェンス）
|
||
- `core/box/ss_os_acquire_box.h` の `ss_os_madvise_guarded()` は **libc/libm/ld.so など DSO 領域を dladdr で検出したら即スキップ** します。
|
||
- DSO に対する madvise 試行は **バグ扱い**。`g_ss_madvise_disabled` / DSO-skip ログを必ず 1 回だけ出し、以降は触らない前提です。
|
||
- 開発/CI では（必要なら）`HAKMEM_SS_MADVISE_DSO_FAILFAST=1` を使って、「DSO に一度でも触ろうとしたら即 abort」するチェックランを追加してください。
|
||
|
||
- madvise / vm.max_map_count 用 健康診断ラン
|
||
- 目的: Superslab OS Box が ENOMEM(vm.max_map_count) に達しても安全に退避できているか、DSO 領域を誤って触っていないかを確認する。
|
||
- 推奨コマンド（C7_SAFE + mid/smallmid, Superslab/madvise 経路の smoke 用）:
|
||
```sh
|
||
HAKMEM_BENCH_MIN_SIZE=257 \
|
||
HAKMEM_BENCH_MAX_SIZE=768 \
|
||
HAKMEM_TINY_HEAP_PROFILE=C7_SAFE \
|
||
HAKMEM_TINY_C7_HOT=1 \
|
||
HAKMEM_TINY_HOTHEAP_V2=0 \
|
||
HAKMEM_SMALL_HEAP_V3_ENABLED=1 \
|
||
HAKMEM_SMALL_HEAP_V3_CLASSES=0x80 \
|
||
HAKMEM_POOL_V2_ENABLED=0 \
|
||
HAKMEM_POOL_V1_FLATTEN_ENABLED=0 \
|
||
HAKMEM_SS_OS_STATS=1 \
|
||
./bench_mid_large_mt_hakmem 5000 256 1
|
||
```
|
||
- チェックポイント:
|
||
- 終了時に `[SS_OS_STATS] ... madvise_enomem=0 madvise_disabled=0` が理想（環境次第で ENOMEM は許容、ただし disabled=1 になっていれば以降の madvise は止まっている）。
|
||
- DSO-skip や DSO Fail-Fast ログが出ていないこと（出た場合は ptr 分類/経路を優先的にトリアージ）。
|
||
|
||
- Pool v1 flatten のプロファイル注意
|
||
- LEGACY プロファイル専用の最適化です。`HAKMEM_TINY_HEAP_PROFILE=C7_SAFE` / `C7_ULTRA_BENCH` のときは **コード側で強制OFF** されます。
|
||
- flatten を触るときの健康診断ラン（LEGACY想定）:
|
||
```sh
|
||
HAKMEM_BENCH_MIN_SIZE=257 \
|
||
HAKMEM_BENCH_MAX_SIZE=768 \
|
||
HAKMEM_TINY_HEAP_PROFILE=LEGACY \
|
||
HAKMEM_POOL_V2_ENABLED=0 \
|
||
HAKMEM_POOL_V1_FLATTEN_ENABLED=1 \
|
||
HAKMEM_POOL_V1_FLATTEN_STATS=1 \
|
||
./bench_mid_large_mt_hakmem 1 1000000 400 1
|
||
```
|
||
- チェックポイント:
|
||
- `[POOL_V1_FLAT] alloc_tls_hit` / `free_tls_hit` が増えていること（flatten 経路が効いている）。
|
||
- `free_fb_*`（page_null / not_mine / other）は**少数**に収まっていること。増えてきたら owner 判定/lookup 側を優先トリアージする。
|
||
|
||
- C6 は Phase C6-FREEZE 中（標準では Tiny/SmallObject/ULTRA に載せない）
|
||
- 標準プロファイル（MIXED_TINYV3_C7_SAFE / C6_HEAVY_LEGACY_POOLV1）は C6 を mid/pool の通常クラスとして扱う。C6_HOT や smallheap(v3/v4)/ULTRA はすべて研究用の opt-in に限定。
|
||
- C6 を触るときは ENV_PROFILE_PRESETS.md の研究プリセット（C6_SMALL_HEAP_V3_EXPERIMENT / C6_SMALL_HEAP_V4_EXPERIMENT など）から開始し、標準プリセットに混ぜ込まないこと。
|
||
- mid/smallmid の性能を攻めるときは、まず pool/mid 側の HotBox 設計（SmallObject v4 や mid 用 ULTRA）を考え、C6 専用の特別扱いは後段フェーズまで凍結する。
|
||
|
||
- C7 ULTRA は UF-3 セグメント版が標準（ENV で OFF に戻せる）
|
||
- `HAKMEM_TINY_C7_ULTRA_ENABLED` デフォルト ON。2MiB セグメント（64KiB ページ, mask 判定）上で carve/push。セグメント外の ptr は必ず既存 v3 free にフォールバックする。
|
||
- ON/OFF の前後で必ず健康診断ランを 1 回ずつ取り、差分が出たらまず ULTRA 側を疑う。
|
||
- ヘッダ軽量化（`HAKMEM_TINY_C7_ULTRA_HEADER_LIGHT`）は研究箱。Mixed/C7-only の A/B を取ってから触ること。デフォルトは OFF。
|
||
- 将来的にヘッダレス設計を広げるときは、まず C7 ULTRA の勝ちパターンを small-object v4（16〜2KiB）にコピーし、各サイズクラスを一つの SmallObjectHotBox v4 に統合してから mid/pool 側を触る。
|
||
|
||
- 一般ルール（壊れたらまず健康診断ラン）
|
||
- Tiny / Superslab / Pool に手を入れたあと、まず上記の健康診断ランを 1 回だけ回してから長尺ベンチ・本番 A/B に進んでください。
|
||
- 健康診断ランが落ちる場合は **新しい最適化を積む前に** Box 境界（ptr 分類 / Superslab OS Box / Pool v1 flatten Box）を優先的に直します。
|
||
- ベンチや評価を始めるときは、`docs/analysis/ENV_PROFILE_PRESETS.md` のプリセット（MIXED_TINYV3_C7_SAFE / C6_HEAVY_LEGACY_POOLV1 / DEBUG_TINY_FRONT_PERF）から必ずスタートし、追加した ENV はメモを残してください。単発の ENV を散らすと再現が難しくなります。
|
||
- 健康診断ラン（簡易チェック）は次の 2 本を必ず通す:
|
||
- Tiny/Mixed: `HAKMEM_PROFILE=MIXED_TINYV3_C7_SAFE ./bench_random_mixed_hakmem 1000000 400 1` （35〜38M ops/s / segv/assert なしで OK）
|
||
- mid/smallmid C6: `HAKMEM_PROFILE=C6_HEAVY_LEGACY_POOLV1 ./bench_mid_large_mt_hakmem 1 1000000 400 1` （約29M ops/s / segv/assert なしで OK）
|
||
- まとめて実行する場合は `scripts/verify_health_profiles.sh` を 1 回叩けば OK（スループットは目安表示のみ、exit code だけで判定）。
|
||
|
||
---
|
||
|
||
## V7 世代の設計メモへの導線（mimalloc に追いつく箱を作るとき）
|
||
|
||
v7 / HAKMEM v3 の設計・実装を触るときは、必ず次の設計ドキュメントから読み始めてください。
|
||
|
||
- `docs/analysis/HAKMEM_V2_GENERATION_SUMMARY.md`
|
||
- v2 世代（ULTRA + MID v3 + v6/v7 研究箱）のまとめと L0〜L3 の層構造。
|
||
- 「ここまでが第1世代・ここから先を v3/v7 で攻める」という地図。
|
||
|
||
- `docs/analysis/SMALLOBJECT_V7_DESIGN.md`
|
||
- SmallObjectHotBox_v7 / SmallSegment_v7 / RegionIdBox の型と責務。
|
||
- v7-0〜v7-4 のフェーズと、「v3 世代でどのクラスを誰が担当するか」の前提。
|
||
|
||
- `docs/analysis/V7_ARCHITECTURE_DECISION_MATRIX.md`
|
||
- mimalloc と v7 の比較表（Free List / Size Class / Lookup / Header 等）。
|
||
- v7-5a（C6 極限最適化）と v7-5b（multi-class 拡張）どちらから攻めるかの判断基準。
|
||
- Intrusive LIFO / headerless / Stats cold path など、次世代で検討する論点一覧。
|
||
|
||
これら 3 つを「設計の正」として扱い、v7 をいじるときは必ず A/B 用プロファイルと Box 境界を先に決めてからコードを触ってください。
|
||
|
||
---
|
||
|
||
## Tiny/ULTRA 層の「完成世代」宣言（2025-12-11）
|
||
|
||
**Tiny/ULTRA 層は C4–C7 ULTRA + v3 backend を前提とした「完成世代」として扱う。**
|
||
今後の大きい変更は **Headerless 系（v6 out-of-band header）/ mid/pool v3 新設計** といった独立ラインでのみ検討。
|
||
Tiny/ULTRA 層本体への追加最適化は Small patch level のみ（Phase SO-BACKEND-OPT-2 等の Header write 削減）を想定。
|
||
詳細は `docs/analysis/PERF_EXEC_SUMMARY_ULTRA_PHASE_20251211.md` 参照。
|
||
|
||
---
|
||
|
||
## v6 研究箱ルール（Phase V6-HDR-0 以降）
|
||
|
||
### 基本方針
|
||
|
||
v6 は **C6-only headerless core** の研究ラインとして、Tiny/ULTRA 完成世代とは**独立して**運用する。
|
||
|
||
### 固定事項
|
||
|
||
1. **C7 ULTRA は触らない**
|
||
- TinyC7UltraBox / C7UltraSegmentBox は frozen。v6 から C7 を呼び出さない。
|
||
- C7 の最適化が必要な場合は ULTRA 側で対応（v6 スコープ外）。
|
||
|
||
2. **v6 は C6-only**
|
||
- `HAKMEM_SMALL_CORE_V6_ENABLED=1` + `HAKMEM_SMALL_CORE_V6_CLASSES=0x40` (C6 のみ)
|
||
- C5/C4 への拡張は研究完了後に検討（Phase V6-HDR-1 以降）
|
||
|
||
3. **Headerless 設計**
|
||
- alloc 時に header byte を書かない（`SMALL_V6_HEADERLESS=1`）
|
||
- free 時は RegionIdBox で ptr 分類 → page_meta へ直接アクセス
|
||
|
||
4. **デフォルト OFF**
|
||
- `HAKMEM_SMALL_CORE_V6_ENABLED=0` がデフォルト
|
||
- 本線 Mixed / C6-heavy は v6 OFF で計測（回帰しない）
|
||
|
||
### ENV 一覧
|
||
|
||
| ENV | Default | 説明 |
|
||
|-----|---------|------|
|
||
| `HAKMEM_SMALL_CORE_V6_ENABLED` | 0 | v6 core 有効化 |
|
||
| `HAKMEM_SMALL_CORE_V6_CLASSES` | 0x40 | 有効クラス (0x40=C6) |
|
||
| `HAKMEM_SMALL_V6_OBSERVE` | 0 | free 入口のログ出力 |
|
||
| `HAKMEM_PAGE_STATS_V6_ENABLED` | 0 | page lifetime stats |
|
||
| `HAKMEM_REGION_ID_V6_OBSERVE` | 0 | RegionIdBox lookup ログ |
|
||
|
||
### 4層 Box Theory
|
||
|
||
```
|
||
L0: ULTRA lanes (C7 frozen)
|
||
L1: TLS Box (SmallTlsLaneV6 / SmallHeapCtxV6)
|
||
L2: Segment / ColdIface (SmallSegmentV6 / ColdIfaceV6)
|
||
L3: Policy / RegionIdBox / PageStatsV6
|
||
```
|
||
|
||
詳細は `docs/analysis/SMALLOBJECT_CORE_V6_DESIGN.md` 参照。
|