From 44273693cc6e0e4a8262fadd27e1231b32da2814 Mon Sep 17 00:00:00 2001 From: "Moe Charm (CI)" Date: Sun, 14 Dec 2025 20:29:28 +0900 Subject: [PATCH] docs: record Phase 10 GO promotion; add Phase 11 instructions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Phase 10 updates: - Mark Phase 10 as promoted (GO +1.89%) - Update CURRENT_TASK.md with Phase 10 results - Clean up absolute paths in PHASE10 docs - Add promotion status to PHASE10 docs Phase 11 instructions: - New: PHASE11_ENV_SNAPSHOT_MAYBE_FAST_1_NEXT_INSTRUCTIONS.md - Target: Consolidate ENV snapshot overhead - Strategy: Merge hakmem_env_snapshot* and tiny_front_v3_snapshot_get into single call - ENV: HAKMEM_ENV_SNAPSHOT_MAYBE_FAST=0/1 - Expected: +1-2% (reduce TLS/ENV read overhead) Files modified: - CURRENT_TASK.md: Phase 10 GO record, Phase 11 next - docs/analysis/PHASE10_FREE_TINY_FAST_MONO_LEGACY_DIRECT_1_AB_TEST_RESULTS.md - docs/analysis/PHASE10_FREE_TINY_FAST_MONO_LEGACY_DIRECT_1_NEXT_INSTRUCTIONS.md Files added: - docs/analysis/PHASE11_ENV_SNAPSHOT_MAYBE_FAST_1_NEXT_INSTRUCTIONS.md 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 --- CURRENT_TASK.md | 22 ++- ...ST_MONO_LEGACY_DIRECT_1_AB_TEST_RESULTS.md | 38 +++-- ..._MONO_LEGACY_DIRECT_1_NEXT_INSTRUCTIONS.md | 9 ++ ...SNAPSHOT_MAYBE_FAST_1_NEXT_INSTRUCTIONS.md | 136 ++++++++++++++++++ 4 files changed, 185 insertions(+), 20 deletions(-) create mode 100644 docs/analysis/PHASE11_ENV_SNAPSHOT_MAYBE_FAST_1_NEXT_INSTRUCTIONS.md diff --git a/CURRENT_TASK.md b/CURRENT_TASK.md index 79922ebd..8d640ad0 100644 --- a/CURRENT_TASK.md +++ b/CURRENT_TASK.md @@ -60,15 +60,25 @@ - コミット: `871034da1` - Rollback: `export HAKMEM_FREE_TINY_FAST_MONO_DUALHOT=0` -### Next: Phase 10（次の芯） +### Phase 10 FREE-TINY-FAST MONO LEGACY DIRECT: monolithic `free_tiny_fast()` の LEGACY direct を C4–C7 へ拡張 — ✅ GO / 本線昇格 -Perf（Phase 9 後, Mixed）で `front_fastlane_try_free` が依然 top（free 側が支配的）。次は **FastLane free / legacy fallback の固定費削減**を狙う。 +結果: Mixed 10-run mean **+1.89%**。nonlegacy_mask（ULTRA/MID/V7）キャッシュにより誤爆を防ぎつつ、Phase 9（C0–C3）で取り切れていない LEGACY 範囲（C4–C7）を direct でカバーした。 + +- 指示書（完了）: `docs/analysis/PHASE10_FREE_TINY_FAST_MONO_LEGACY_DIRECT_1_NEXT_INSTRUCTIONS.md` +- 実装 + A/B: `docs/analysis/PHASE10_FREE_TINY_FAST_MONO_LEGACY_DIRECT_1_AB_TEST_RESULTS.md` +- コミット: `71b1354d3` +- ENV: `HAKMEM_FREE_TINY_FAST_MONO_LEGACY_DIRECT=0/1`（default ON / opt-out） +- Rollback: `export HAKMEM_FREE_TINY_FAST_MONO_LEGACY_DIRECT=0` + +### Next: Phase 11（次の芯） + +Perf（Phase 10 後, Mixed）で残っている “次の固定費” は **ENV snapshot 系（`hakmem_env_snapshot*` / `tiny_front_v3_snapshot_get`）** と **unified_cache_push** が目立つ。 候補（GO を狙う小パッチ）: -1) **Phase 10: FREE-TINY-FAST “LEGACY direct” 拡張（C4–C7 を含む、断定できる範囲だけ）** - - 目的: `free_tiny_fast()` の “policy/route/ENV チェック” の残り固定費を削減し、`front_fastlane_try_free` を更に薄くする - - 方針: 断定できる条件（route snapshot / no-learner / no-larson-fix 等）のみ direct → それ以外は既存経路へ（Fail-Fast） - - 指示書: `docs/analysis/PHASE10_FREE_TINY_FAST_MONO_LEGACY_DIRECT_1_NEXT_INSTRUCTIONS.md` +1) **Phase 11: ENV Snapshot “maybe-fast” API（enabled+snapshot+front_snap を 1 回に集約）** + - 目的: `tiny_legacy_fallback_free_base()` を中心に、`hakmem_env_snapshot_enabled()` / `hakmem_env_snapshot()` / `tiny_front_v3_snapshot_get()` の固定費を削減 + - 方針: ENV gate は維持しつつ、hot path は “cached gate + cached front_snap ptr” だけで判定（Fail-Fast / refresh は既存の箱境界へ） + - 指示書: `docs/analysis/PHASE11_ENV_SNAPSHOT_MAYBE_FAST_1_NEXT_INSTRUCTIONS.md` ## 更新メモ（2025-12-14 Phase 5 E5-3 Analysis - Strategic Pivot） diff --git a/docs/analysis/PHASE10_FREE_TINY_FAST_MONO_LEGACY_DIRECT_1_AB_TEST_RESULTS.md b/docs/analysis/PHASE10_FREE_TINY_FAST_MONO_LEGACY_DIRECT_1_AB_TEST_RESULTS.md index 8605c24e..54fda7b6 100644 --- a/docs/analysis/PHASE10_FREE_TINY_FAST_MONO_LEGACY_DIRECT_1_AB_TEST_RESULTS.md +++ b/docs/analysis/PHASE10_FREE_TINY_FAST_MONO_LEGACY_DIRECT_1_AB_TEST_RESULTS.md @@ -1,5 +1,13 @@ # Phase 10: FREE-TINY-FAST MONO LEGACY DIRECT A/B テスト結果 +## Status（2025-12-14） + +**✅ GO / 本線昇格（+1.89% Mixed 10-run）** + +- コミット: `71b1354d3` +- Preset: `core/bench_profile.h`（`MIXED_TINYV3_C7_SAFE` で default ON） +- Rollback: `export HAKMEM_FREE_TINY_FAST_MONO_LEGACY_DIRECT=0` + ## 実行日時 2025-12-14 @@ -9,13 +17,13 @@ Phase 9（C0-C3 DUALHOT）の成功を受けて、Phase 10 では C4-C7 を含 ## 実装内容 ### Patch 1: ENV gate 箱を追加（L0） -- ファイル: `/mnt/workdisk/public_share/hakmem/core/box/free_tiny_fast_mono_legacy_direct_env_box.h` +- ファイル: `core/box/free_tiny_fast_mono_legacy_direct_env_box.h` - ENV変数: `HAKMEM_FREE_TINY_FAST_MONO_LEGACY_DIRECT=0/1`（default 0） - probe window: 64（bench_profile の putenv 競合に耐える） - nonlegacy_mask キャッシュ機能を追加（Phase POLICY-FAST-PATH-V2 の計算を初期化時に 1 回だけ実行） ### Patch 2: `free_tiny_fast()` に early-exit を追加（L1） -- ファイル: `/mnt/workdisk/public_share/hakmem/core/front/malloc_tiny_fast.h` +- ファイル: `core/front/malloc_tiny_fast.h` - Phase 9（C0-C3 direct）の後に、Phase 10（C4-C7 拡張）の条件を追加 - 条件: 1. `HAKMEM_FREE_TINY_FAST_MONO_LEGACY_DIRECT=1` @@ -24,11 +32,11 @@ Phase 9（C0-C3 DUALHOT）の成功を受けて、Phase 10 では C4-C7 を含 4. `tiny_env_cfg()->larson_fix == 0` ### Patch 3: 見える化（最小） -- ファイル: `/mnt/workdisk/public_share/hakmem/core/box/free_path_stats_box.h` +- ファイル: `core/box/free_path_stats_box.h` - カウンタ追加: `uint64_t mono_legacy_direct_hit;` ### Patch 4: A/B 用の cleanenv 追記 -- ファイル: `/mnt/workdisk/public_share/hakmem/scripts/run_mixed_10_cleanenv.sh` +- ファイル: `scripts/run_mixed_10_cleanenv.sh` - ENV変数追加: `export HAKMEM_FREE_TINY_FAST_MONO_LEGACY_DIRECT=${HAKMEM_FREE_TINY_FAST_MONO_LEGACY_DIRECT:-0}` ## A/B テスト結果 @@ -153,17 +161,19 @@ scripts/verify_health_profiles.sh ## 次のステップ -### 1. Preset 追加（推奨） -`core/bench_profile.h` の `MIXED_TINYV3_C7_SAFE` プリセットに追加: -```c -bench_setenv_default("HAKMEM_FREE_TINY_FAST_MONO_LEGACY_DIRECT","1"); -``` +### 昇格（GO）— 完了 -### 2. C6_HEAVY_LEGACY_POOLV1 プリセットへの追加 -今回の結果では C6-heavy でも改善が見られたが、MID v3 有効時の誤爆防止のため、慎重に検討する: -- Option A: 追加しない（安全側、現状維持） -- Option B: 追加する（C6 以外のクラスの改善を取る） -- **推奨**: Option A（誤爆防止のため未設定のまま） +Phase 10 は本線に昇格済み（`71b1354d3`）。 + +- `core/bench_profile.h`: `MIXED_TINYV3_C7_SAFE` に `HAKMEM_FREE_TINY_FAST_MONO_LEGACY_DIRECT=1` +- Rollback: `export HAKMEM_FREE_TINY_FAST_MONO_LEGACY_DIRECT=0` + +### C6_HEAVY_LEGACY_POOLV1 について + +今回の A/B では C6-heavy でも +7.86% が出たが、これは「C6 を誤って direct した」結果ではなく、**C6 以外の LEGACY クラス**が direct になった寄与と考えられる。 + +運用は保守的に: +- `C6_HEAVY_LEGACY_POOLV1` は preset 未設定のまま（必要なら専用プリセットを作って opt-in） ### 3. Rollback 手順 問題が発生した場合、同一バイナリで即座に無効化可能: diff --git a/docs/analysis/PHASE10_FREE_TINY_FAST_MONO_LEGACY_DIRECT_1_NEXT_INSTRUCTIONS.md b/docs/analysis/PHASE10_FREE_TINY_FAST_MONO_LEGACY_DIRECT_1_NEXT_INSTRUCTIONS.md index 2d66ff4f..3aa712a2 100644 --- a/docs/analysis/PHASE10_FREE_TINY_FAST_MONO_LEGACY_DIRECT_1_NEXT_INSTRUCTIONS.md +++ b/docs/analysis/PHASE10_FREE_TINY_FAST_MONO_LEGACY_DIRECT_1_NEXT_INSTRUCTIONS.md @@ -1,5 +1,14 @@ # Phase 10: FREE-TINY-FAST MONO LEGACY DIRECT（FastLane free 固定費削減）次の指示書 +## Status（2025-12-14） + +**✅ GO / 本線昇格（+1.89% Mixed 10-run）** + +- A/B 結果: `docs/analysis/PHASE10_FREE_TINY_FAST_MONO_LEGACY_DIRECT_1_AB_TEST_RESULTS.md` +- コミット: `71b1354d3` +- Preset: `core/bench_profile.h` に `HAKMEM_FREE_TINY_FAST_MONO_LEGACY_DIRECT=1`（`MIXED_TINYV3_C7_SAFE`） +- Rollback: `export HAKMEM_FREE_TINY_FAST_MONO_LEGACY_DIRECT=0` + ## 0. 目的（狙い） Phase 6 FastLane + Phase 6-2 Free DeDup + Phase 9 MONO DUALHOT により、Mixed の free は主に: diff --git a/docs/analysis/PHASE11_ENV_SNAPSHOT_MAYBE_FAST_1_NEXT_INSTRUCTIONS.md b/docs/analysis/PHASE11_ENV_SNAPSHOT_MAYBE_FAST_1_NEXT_INSTRUCTIONS.md new file mode 100644 index 00000000..44537b2c --- /dev/null +++ b/docs/analysis/PHASE11_ENV_SNAPSHOT_MAYBE_FAST_1_NEXT_INSTRUCTIONS.md @@ -0,0 +1,136 @@ +# Phase 11: ENV Snapshot “maybe-fast” API（hot-path の enabled/snapshot/front_snap を 1 回に集約）次の指示書 + +## 0. 目的（狙い） + +Phase 10 までで `free_tiny_fast()` 側の policy/route 固定費はかなり削れたが、Perf（Phase 10 後, Mixed）では次が目立つ: + +- `hakmem_env_snapshot` / `hakmem_env_snapshot_enabled`（合計 ~2%） +- `tiny_front_v3_snapshot_get`（~1%） + +これらは主に `tiny_legacy_fallback_free_base()` などの **超ホット経路で毎回呼ばれている “設定参照の固定費”**。 + +Phase 11 の狙いは、ENV gate（戻せる）を維持したまま **hot path の参照回数を 1 回に集約**し、同時に `tiny_front_v3_snapshot_get()` の “ready-check” を hot から消すこと。 + +## 1. 方針（Box Theory） + +- 箱（L0/L1/L2）: + - L0: `HakmemEnvSnapshotBox`（既存）に “maybe-fast API” を追加 + - L1: `tiny_legacy_fallback_free_base()` / `malloc_tiny_fast_for_class()` などの hot call sites を段階移行 + - L2: refresh（`bench_profile`）は既存の `hakmem_env_snapshot_refresh_from_env()` に統合（変換点 1 箇所） +- 境界: + - “ENV→cached state” の変換点は **refresh 関数 1 箇所**に固定 + - hot path は「cached を読むだけ」 +- 戻せる: + - 既存の `HAKMEM_ENV_SNAPSHOT=0/1` を維持（snapshot が OFF のとき旧経路に落ちる） +- Fail-Fast: + - snapshot が不整合（ready==0 等）の場合は init/refresh を通す（隠さない） +- 見える化（最小）: + - perf の self% で `hakmem_env_snapshot*` / `tiny_front_v3_snapshot_get` が落ちることを確認（新規カウンタは増やさない） + +## 2. 設計（要点） + +### 2.1 追加する hot API + +`hakmem_env_snapshot_enabled()` + `hakmem_env_snapshot()` の二段をやめ、**1 回で “使えるなら snapshot ptr” を返す** API を追加する: + +- `hakmem_env_snapshot_maybe_fast() -> const HakmemEnvSnapshot* | NULL` + - 返り値が non-NULL: snapshot 有効（`HAKMEM_ENV_SNAPSHOT=1`）かつ ready + - NULL: snapshot 無効 → 既存の個別 ENV gate 経路へ + +これにより、call site は: + +- “enabled 判定” と “snapshot 取得” の重複を消せる +- `g_hakmem_env_snapshot_ctor_mode` の分岐を hot から消せる（gate だけを見る） + +### 2.2 `TinyFrontV3Snapshot*` を snapshot 内に保持 + +`tiny_legacy_fallback_free_base()` の hot path で `tiny_front_v3_snapshot_get()` が頻発しているため、 +`HakmemEnvSnapshot` に **`front_v3_snap`（ptr）をキャッシュ**する。 + +- snapshot init/refresh 時に `tiny_front_v3_snapshot_init()` を呼んで `g_tiny_front_v3_snapshot_ready=1` を確定 +- `front_v3_snap = &g_tiny_front_v3_snapshot`（front v3 が無効なら NULL） +- hot path は `front_v3_snap` を読むだけ（ready-check をしない） + +## 3. 実装指示（小パッチ順） + +### Patch 1: `HakmemEnvSnapshot` を拡張（L0） + +対象: +- `core/box/hakmem_env_snapshot_box.h` + +追加: +- `typedef struct TinyFrontV3Snapshot TinyFrontV3Snapshot;`（前方宣言で include を増やさない） +- `const TinyFrontV3Snapshot* front_v3_snap;` を `HakmemEnvSnapshot` に追加 + +### Patch 2: snapshot load/refresh で `front_v3_snap` を確定（L0） + +対象: +- `core/box/hakmem_env_snapshot_box.c` + +やること: +- `#include "tiny_front_v3_env_box.h"` を追加（型と extern に必要） +- `snap->tiny_front_v3_enabled` が true のとき: + - `tiny_front_v3_snapshot_init();` + - `snap->front_v3_snap = &g_tiny_front_v3_snapshot;` +- false のとき: + - `snap->front_v3_snap = NULL;` + +（refresh でも同様に上書きする） + +### Patch 3: “maybe-fast” API を追加（L0） + +対象: +- `core/box/hakmem_env_snapshot_box.h` + +追加: +- `static inline const HakmemEnvSnapshot* hakmem_env_snapshot_maybe_fast(void);` + +仕様: +- gate==1 のとき `&g_hakmem_env_snapshot` を返す（ready==0 なら init） +- gate==0 のとき NULL +- gate==-1 のとき getenv して gate を確定（既存挙動互換） + +### Patch 4: 超ホット call site を 1 箇所ずつ移行（L1） + +優先順（ROI 高い順）: +1) `core/box/tiny_legacy_fallback_box.h` + - `hakmem_env_snapshot_enabled()` / `hakmem_env_snapshot()` / `tiny_front_v3_snapshot_get()` を廃止 + - `env = hakmem_env_snapshot_maybe_fast();` と `env->front_v3_snap` に置換 +2) `core/front/malloc_tiny_fast.h` + - C7 ULTRA gate などの `hakmem_env_snapshot_enabled()` 分岐を `env = hakmem_env_snapshot_maybe_fast()` へ置換 +3) `core/box/tiny_metadata_cache_hot_box.h` + - `metadata_cache_eff` 判定を `env ? env->tiny_metadata_cache_eff : ...` へ置換 + +（その他の call site は Phase 11-2 で拡張でも OK） + +## 4. A/B（推奨） + +この Phase は “既存機能（ENV snapshot）” の内部固定費削減であり、挙動差は出ない設計。 + +最低限: +- Mixed 10-run を Phase 11 前後で比較（+1.0% 以上で GO） +- perf で `hakmem_env_snapshot*` / `tiny_front_v3_snapshot_get` が落ちることを確認 + +コマンド例: +```sh +scripts/run_mixed_10_cleanenv.sh +perf record -F 199 -o /tmp/perf_phase11.data -- env -i PATH="$PATH" HAKMEM_PROFILE=MIXED_TINYV3_C7_SAFE ./bench_random_mixed_hakmem 300000000 400 1 +perf report --stdio -i /tmp/perf_phase11.data --no-children --percent-limit 0.5 | head +``` + +判定（Mixed 10-run mean）: +- GO: **+1.0% 以上** +- NEUTRAL: **±1.0%** +- NO-GO: **-1.0% 以下** + +## 5. 健康診断（必須） + +```sh +scripts/verify_health_profiles.sh +``` + +## 6. Rollback + +- 最小 rollback: `export HAKMEM_ENV_SNAPSHOT=0`（snapshot 自体を無効化） +- コード rollback: Phase 11 のコミットを revert（この Phase は “内部最適化” のため revert が実用） +