hakmem/docs/analysis/PHASE4_E3_ENV_CONSTRUCTOR_INIT_DESIGN.md

Phase 4 E3-4: ENV Constructor Init 設計メモ

目的

E1 で統合した ENV snapshot の lazy init check（3.22% self%）を排除。

期待: +0.5-1.5% 改善

---

結果（A/B テスト）

初回観測（参考）

初回は +4.75% を観測したが、再現しなかった（環境/ノイズの可能性が高い）。

再検証（決定）

判定: ❌ NO-GO / FROZEN

Metric	Baseline (CTOR=0)	Optimized (CTOR=1)	Delta
Mean	47.55M ops/s	46.86M ops/s	-1.44%
Median	47.46M ops/s	46.97M ops/s	-1.03%

結論:

• constructor init は “安全” だが、性能面では 現状の hot path では得にならない
• 研究箱として保持するが default OFF のまま freeze

---

現状分析

E1 完了後の状態

• hakmem_env_snapshot_enabled(): 3.22% self%（perf profile）
• 原因: 毎回の lazy init check（static int g = -1 + getenv()）

// 現在の実装（core/box/hakmem_env_snapshot_box.h:51-62）
static inline bool hakmem_env_snapshot_enabled(void) {
    static int g = -1;
    if (__builtin_expect(g == -1, 0)) {  // ← この分岐が 3.22%
        const char* e = getenv("HAKMEM_ENV_SNAPSHOT");
        if (e && *e) {
            g = (*e == '1') ? 1 : 0;
        } else {
            g = 0;
        }
    }
    return g != 0;
}

問題

1. 分岐コスト: if (g == -1) が hot path で毎回評価
2. 予測ミス: first call で branch misprediction
3. 関数呼び出しオーバーヘッド: inline でも分岐は残る

---

設計

アプローチ: Constructor Init + Direct Read

// 新しい実装
static int g_hakmem_env_snapshot_gate = -1;

__attribute__((constructor(101)))  // priority 101: after libc init
static void hakmem_env_snapshot_gate_init(void) {
    const char* e = getenv("HAKMEM_ENV_SNAPSHOT");
    g_hakmem_env_snapshot_gate = (e && *e == '1') ? 1 : 0;
}

static inline bool hakmem_env_snapshot_enabled(void) {
    return g_hakmem_env_snapshot_gate != 0;  // No branch (just load + compare)
}

利点

1. 分岐削減: if (g == -1) 完全排除
2. 一度だけ: getenv() は main() 前に 1 回のみ
3. キャッシュ効率: global read は TLS より高速（L1 hit 率高い）

リスク

リスク	対策
putenv() 後の変更が反映されない	bench_profile の hakmem_env_snapshot_refresh_from_env() で gate/snapshot を同期
constructor order	priority 101 で libc init 後を保証
fork() 安全性	hakmem は fork-safe 設計済み

---

Box Theory（実装計画）

L0: Env（戻せる）

HAKMEM_ENV_SNAPSHOT_CTOR=0/1  # default: 0（OFF）

• ON (=1): Constructor init を使用（lazy check なし）
• OFF (=0): 従来の lazy init を使用（rollback 可能）

L1: ENV Constructor Box（境界: 1 箇所）

変更対象

• core/box/hakmem_env_snapshot_box.h (変更)
  • hakmem_env_snapshot_enabled() を 2 つのモードで実装
• core/box/hakmem_env_snapshot_box.c (変更)
  • Constructor 関数を追加

---

実装指示

Patch 1: Constructor Init Gate

ファイル: core/box/hakmem_env_snapshot_box.c

// Global gate (not static local - avoids lazy init)
int g_hakmem_env_snapshot_gate = -1;
int g_hakmem_env_snapshot_ctor_mode = -1;

// Constructor: run before main()
__attribute__((constructor(101)))
static void hakmem_env_snapshot_gate_ctor(void) {
    // Read HAKMEM_ENV_SNAPSHOT_CTOR (default OFF)
    const char* ctor_env = getenv("HAKMEM_ENV_SNAPSHOT_CTOR");
    g_hakmem_env_snapshot_ctor_mode = (ctor_env && *ctor_env == '1') ? 1 : 0;

    if (g_hakmem_env_snapshot_ctor_mode) {
        // Constructor mode: init gate now
        const char* e = getenv("HAKMEM_ENV_SNAPSHOT");
        g_hakmem_env_snapshot_gate = (e && *e == '1') ? 1 : 0;
    }
}

Patch 2: Dual-Mode Enabled Check

ファイル: core/box/hakmem_env_snapshot_box.h

// Global gate state (defined in .c)
extern int g_hakmem_env_snapshot_gate;
extern int g_hakmem_env_snapshot_ctor_mode;

static inline bool hakmem_env_snapshot_enabled(void) {
    // Fast path: constructor mode (no lazy check, just global read).
    // Note: do not attach a fixed branch hint here; it will be wrong for one mode.
    if (g_hakmem_env_snapshot_ctor_mode == 1) {
        return g_hakmem_env_snapshot_gate != 0;
    }

    // Slow path: legacy lazy init (fallback)
    if (__builtin_expect(g_hakmem_env_snapshot_gate == -1, 0)) {
        const char* e = getenv("HAKMEM_ENV_SNAPSHOT");
        g_hakmem_env_snapshot_gate = (e && *e == '1') ? 1 : 0;
    }
    return g_hakmem_env_snapshot_gate != 0;
}

---

A/B テスト計画

Test Matrix

Profile	Iterations	Runs	Command
Mixed	20M	10	./bench_random_mixed_hakmem 20000000 400 1

Baseline

HAKMEM_PROFILE=MIXED_TINYV3_C7_SAFE HAKMEM_ENV_SNAPSHOT=1 HAKMEM_ENV_SNAPSHOT_CTOR=0 \
  ./bench_random_mixed_hakmem 20000000 400 1

Optimized

HAKMEM_PROFILE=MIXED_TINYV3_C7_SAFE HAKMEM_ENV_SNAPSHOT=1 HAKMEM_ENV_SNAPSHOT_CTOR=1 \
  ./bench_random_mixed_hakmem 20000000 400 1

判定基準

• GO: +0.5% 以上
• NEUTRAL: ±0.5%（研究箱維持）
• NO-GO: -0.5% 以下

---

期待値の根拠

なぜ +0.5-1.5% か？

1. 現在のオーバーヘッド: 3.22% self%
2. 削減分: lazy init check の分岐コスト（~10-15 cycles per call）
3. 削減率: ~15-30% of 3.22% → 0.5-1.0%
4. 追加効果: better branch prediction（warm path に分岐なし）

---

非目標

• snapshot refresh API の変更（putenv sync は既存 API で対応）
• E1 の構造変更（consolidation は維持）
• 他の ENV gate の constructor 化（E3-4 は hakmem_env_snapshot_enabled のみ）