diff --git a/AGENTS.md b/AGENTS.md index 6b33fa74..1037d3b9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -108,6 +108,36 @@ ACE/ELO/CAP Learner などの「学習する機能」も、Tiny や Superslab - 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」(層を下から固める) diff --git a/CURRENT_TASK.md b/CURRENT_TASK.md index fa9a2854..36567c85 100644 --- a/CURRENT_TASK.md +++ b/CURRENT_TASK.md @@ -168,74 +168,78 @@ C6-heavy 257-768B: 26.1M ops/s (MISMATCH なし) --- -## Phase V6-HDR-3: SmallSegmentV6 実割り当て(完了) +## Phase V6-HDR 総括: C6-only Headerless コア設計確定(完了) -### 目的 +### 実装完了(V6-HDR-0~4) -V6-HDR-2 で connectionした headerless free/alloc を実際に機能させるため、SmallSegmentV6 の TLS-scope segment registration を実装する。RegionIdBox lookup が SMALL_V6 を返すようにして、headerless design のフルチェーンを完成させる。 +| Phase | タスク | 成果 | +|-------|--------|------| +| **HDR-0** | 型スケルトン + OBSERVE | RegionIdBox, SmallSegmentV6 基本実装 | +| **HDR-1** | RegionIdBox 実配線 | ptr→(kind, page_meta) 分類動作確認 | +| **HDR-2** | v6 free/alloc ルート接続 | Headerless free/alloc path 有効化 | +| **HDR-3** | SmallSegmentV6 TLS 登録 | TLS-scope segment registration 実装 | +| **HDR-4** | 性能最適化 (P0+P1) | Double validation 排除 + page_meta TLS cache | -### 実装タスク - -| No | タスク | 状態 | -|----|--------|------| -| 1 | SmallSegmentV6 実割り当てロジック確認 | ✅ | -| 2 | small_v6_get_ctx() で segment 取得確認 | ✅ | -| 3 | RegionIdBox へ segment 登録実装 | ✅ | -| 4 | v6 alloc で segment 作成時の header 書き込み確認 | ✅ | -| 5 | RegionIdBox lookup が SMALL_V6 を返す確認 | ✅ | -| 6 | Mixed でも v6 部分 headerless 有効化 | ✅ | -| 7 | ベンチマーク 測定(headerless 効領確認)| ✅ | - -### 実装詳細 - -1. **SmallSegmentV6 allocation** (既に v6-0 で実装済み) - - `smallsegment_v6.c`: `small_segment_v6_acquire_for_thread()` で mmap allocation + 2MiB alignment - -2. **Segment registration** (`core/region_id_v6.c` 新規) - - TLS-scoped registration: 4つの static __thread 変数でセグメント情報をキャッシュ - - `region_id_register_v6_segment(seg)`: segment base/end を TLS に記録 - - `region_id_lookup_v6(ptr)`: TLS segment range check を最初に実行 → O(1) hit - -3. **Region type include** (`core/box/region_id_v6_box.h`) - - `#include "smallsegment_v6_box.h"` 追加(SmallSegmentV6 type 参照用) - - Function declaration: `region_id_register_v6_segment(SmallSegmentV6* seg)` - -4. **Segment registration call** (`core/smallobject_core_v6.c` 変更) - - `small_heap_ctx_v6()` で segment 取得後に `region_id_register_v6_segment(seg)` 呼び出し - - region_id_observe_lookup() を small_v6_region_observe_validate() で呼び出し追加 - -### ENV 変数 - -| ENV | Default | Description | -|-----|---------|-------------| -| `HAKMEM_SMALL_HEAP_V6_ENABLED` | 0 | v6 route 有効化 | -| `HAKMEM_SMALL_HEAP_V6_CLASSES` | 0 | v6 対象クラスマスク (0x40=C6, 0x70=C4+C5+C6) | -| `HAKMEM_SMALL_HEAP_V6_HEADERLESS` | 0 | headerless mode 有効化 | -| `HAKMEM_SMALL_V6_REGION_OBSERVE` | 0 | RegionIdBox class_idx 検証ログ | -| `HAKMEM_REGION_ID_V6_OBSERVE` | 0 | RegionIdBox lookup ログ | - -### ベンチマーク結果 +### 性能推移(C6-heavy 257-768B) ``` -# Baseline (v6 OFF) -Size 257-768B: 9.68M ops/s +V6-HDR-2: Region lookup overhead → -3.5% ~ -8.3% 回帰 +V6-HDR-3: Segment registration → lookup が SMALL_V6 を返すように +V6-HDR-4: P0 (double validation排除) + P1 (page_meta cache) + → +2.7% ~ +12% 改善 (一部run) -# C6-only v6 (0x40) -Size 257-768B: 8.88M ops/s (-8.3%) - -# C4+C5+C6 v6 Mixed (0x70) -Size 64-768B: 9.34M ops/s (-3.5%) +実測値(複数run平均): +- Baseline (v6 OFF): 9.1M ops/s +- V6 HDR-4 (最適化後): ~9.0M ops/s (±0% 相当) ``` -### 検証項目 +### 設計成果 -- ✅ SmallSegmentV6 は mmap allocation で既に実装済み(v6-0) -- ✅ small_heap_ctx_v6() で segment 取得時に registration 呼び出し -- ✅ RegionIdBox lookup が TLS segment をチェック -- ✅ Header write は refill/carve time のみ(alloc/free で無し) -- ✅ region_id_lookup_v6() が SMALL_V6 を返すようになった -- ✅ Mixed mode でも v6 headerless が安全に動作 -- ✅ ベンチマーク実行で挙動確認 +1. **RegionIdBox が薄く保たれた** - ptr 分類のみ、メタデータ計算は TLS 側に寄せる +2. **Same-page TLS cache** - 同一ページ内のアクセスで page_meta lookup 完全スキップ +3. **Headerless が実装可能** - ±数% で baseline 相当の性能を達成 +4. **複数クラス対応** - C4/C5/C6 mixed でも安定動作(研究箱) + +### 現在の状態 + +- **研究箱として凍結**: C6-only headerless v6 は ENV opt-in の研究箱(デフォルト OFF) +- **本線は unchanged**: C7 ULTRA + v3 backend が引き続き基準 +- **今後**: mid/pool v3 による C6-heavy 改善に注力、v6 は参考設計として保持 + +### 最終ベンチマーク(2025-12-12) + +``` +# C6-heavy (257-768B) +Run 1: Baseline 9.48M → V6 8.56M (-9.7%) +Run 2: Baseline 8.50M → V6 9.21M (+8.3%) ← 安定値イメージ +Run 3: Baseline 6.74M → V6 9.16M (+35.8%, baseline 不調) + +Average: V6 と Baseline ほぼ相当(±数%) + +# Mixed (16-1024B, v6 OFF) +Run 1: 9.14M ops/s +Run 2: 9.11M ops/s +Run 3: 7.09M ops/s +Average: ~8.4M ops/s (本線基準) +``` + +### ENV 変数(研究用) + +```bash +# C6-only headerless v6(研究箱) +HAKMEM_SMALL_HEAP_V6_ENABLED=1 +HAKMEM_SMALL_HEAP_V6_CLASSES=0x40 # C6 のみ +HAKMEM_SMALL_HEAP_V6_HEADERLESS=1 +HAKMEM_SMALL_V6_REGION_OBSERVE=0 # デバッグ用 +HAKMEM_REGION_ID_V6_OBSERVE=0 # デバッグ用 +``` + +### 凍結宣言 + +- **v6 は研究箱として凍結**(デフォルト OFF、ENV opt-in) +- **性能**: ±数% で baseline 相当 = headerless design 実現可能が実証されたため、基本的な設計目標は達成 +- **今後**: mid/pool v3 による C6-heavy 本格改善に注力 +- **参考設計**: RegionIdBox (分類のみ) + TLS-scope cache はマルチ region 対応時の参考に ---