hakmem/docs/specs/ENV_VARS.md

HAKMEM Environment Variables (Tiny focus)

Core toggles

• HAKMEM_WRAP_TINY=1
  • Tiny allocatorを有効化（直リンク）
• HAKMEM_TINY_USE_SUPERSLAB=0/1
  • SuperSlab経路のON/OFF（既定ON）

SFC (Super Front Cache) stats / A/B

• HAKMEM_SFC_ENABLE=0/1
  • Box 5‑NEW: Super Front Cache を有効化（既定OFF; A/B用）。
• HAKMEM_SFC_CAPACITY=16..256 / HAKMEM_SFC_REFILL_COUNT=8..256
  • SFCの容量とリフィル個数（例: 256/128）。
• HAKMEM_SFC_STATS_DUMP=1
  • プロセス終了時に SFC 統計をstderrへダンプ（alloc_hits/misses, refill_calls など）。
  • 使い方: make CFLAGS+=" -DHAKMEM_DEBUG_COUNTERS=1" larson_hakmem; HAKMEM_SFC_ENABLE=1 HAKMEM_SFC_STATS_DUMP=1 ./larson_hakmem …

Larson defaults (publish→mail→adopt)

• 忘れがちな必須変数をスクリプトで一括設定するため、scripts/run_larson_defaults.sh を用意しています。
• 既定で以下を export します（A/B は環境変数で上書き可能）:
  • HAKMEM_TINY_USE_SUPERSLAB=1 / HAKMEM_TINY_MUST_ADOPT=1 / HAKMEM_TINY_SS_ADOPT=1
  • HAKMEM_TINY_FAST_CAP=64
  • HAKMEM_TINY_FAST_SPARE_PERIOD=8 ← fast-tier から Superslab へ戻して publish 起点を作る
• HAKMEM_TINY_MAILBOX_SLOWDISC=1
• HAKMEM_TINY_MAILBOX_SLOWDISC_PERIOD=256

Front Gate (A/B for boxified fast path)

• HAKMEM_TINY_FRONT_GATE_BOX=1 — Use Front Gate Box implementation (SFC→SLL) for fast-path pop/push/cascade. Default 0. Safe to toggle during builds via make EXTRA_CFLAGS+=" -DHAKMEM_TINY_FRONT_GATE_BOX=1".
  • Debug visibility（任意）: HAKMEM_TINY_RF_TRACE=1
  • Force-notify（任意, デバッグ補助）: HAKMEM_TINY_RF_FORCE_NOTIFY=1
• モード別（tput/pf）で Superslab サイズと cache/precharge も設定:
  • tput: HAKMEM_TINY_SS_FORCE_LG=21, HAKMEM_TINY_SS_CACHE=0, HAKMEM_TINY_SS_PRECHARGE=0
  • pf: HAKMEM_TINY_SS_FORCE_LG=20, HAKMEM_TINY_SS_CACHE=4, HAKMEM_TINY_SS_PRECHARGE=1

Ultra Tiny (SLL-only, experimental)

• HAKMEM_TINY_ULTRA=0/1
  • Ultra TinyモードのON/OFF（SLL中心の最小ホットパス）
• HAKMEM_TINY_ULTRA_VALIDATE=0/1
  • UltraのSLLヘッド検証（安全性重視時に1、性能計測は0推奨）
• HAKMEM_TINY_ULTRA_BATCH_C{0..7}=N
  • クラス別リフィル・バッチ上書き（例: class=3(64B) → C3）
• HAKMEM_TINY_ULTRA_SLL_CAP_C{0..7}=N
  • クラス別SLL上限上書き

SuperSlab adopt/publish（実験）

• HAKMEM_TINY_SS_ADOPT=0/1
  • SuperSlab の publish/adopt + remote drain + owner移譲を有効化（既定OFF）。
  • 4T Larson など cross-thread free が多いワークロードで再利用密度を高めるための実験用スイッチ。
  • ON 時は一部の単体性能（1T）が低下する可能性があるため A/B 前提で使用してください。
  • 備考: 環境変数を未設定の場合でも、実行中に cross-thread free が検出されると自動で ON になる（auto-on）。
• HAKMEM_TINY_SS_ADOPT_COOLDOWN=4
  • adopt 再試行までのクールダウン（スレッド毎）。0=無効。
• HAKMEM_TINY_SS_ADOPT_BUDGET=8
  • superslab_refill() 内で adopt を試行する最大回数（0-32）。
• HAKMEM_TINY_SS_ADOPT_BUDGET_C{0..7}
  • クラス別の adopt 予算個別上書き（0-32）。指定時は HAKMEM_TINY_SS_ADOPT_BUDGET より優先。
• HAKMEM_TINY_SS_REQTRACE=1
  • 収穫ゲート（guard）や ENOMEM フォールバック、slab/SS 採用のリクエストトレースを標準エラーに出力（軽量）。
• HAKMEM_TINY_RF_FORCE_NOTIFY=0/1（デバッグ補助）
  • remote queue がすでに非空（old!=0）でも、slab_listed==0 の場合に publish を強制通知。
  • 初回の空→非空通知を見逃した可能性をあぶり出す用途に有効（A/B 推奨）。

Ready List（Refill最適化の箱）

• 2025-12 cleanup: Ready系ENVは廃止。Ready ringは常時有効、幅/予算は固定（width=TINY_READY_RING, budget=1）。

Background Remote Drain（束ね箱・軽量ステップ）

• 2025-12 cleanup: BG Remote系ENV（HAKMEM_TINY_BG_REMOTE*）は廃止。BGリモート/aggregatorは固定OFF。

Ready Aggregator（BG, 非破壊peek）

• 2025-12 cleanup: Ready Aggregator系ENVも廃止（固定OFF）。

Registry 窓（探索コストのA/B）

• HAKMEM_TINY_REG_SCAN_MAX=N
  • Registry の“小窓”で走査する最大エントリ数（既定256）。
  • 値を小さくすると superslab_refill() と mmap直前ゲートでの探索コストが減る一方、adopt 命中率が低下し OOM/新規mmap が増える可能性あり。
  • Tiny‑Hotなど命中率が高い場合は 64/128 などをA/B推奨。

Mid 向け簡素化リフィル（128–1024B向けの分岐削減）

• HAKMEM_TINY_MID_REFILL_SIMPLE=0/1
  • クラス>=4（128B以上）で、sticky/hot/mailbox/registry/adopt の多段探索をスキップし、
    1. 既存TLSのSuperSlabに未使用Slabがあれば直接初期化→bind、
    2. なければ新規SuperSlabを確保して先頭Slabをbind、の順に簡素化します。
  • 目的: superslab_refill() 内の分岐と走査を削減（tput重視A/B用）。
  • 注意: adopt機会が減るため、PFやメモリ効率は変動します。常用前にA/B必須。

Mid 向けリフィル・バッチ（SLL補強）

• HAKMEM_TINY_REFILL_COUNT_MID=N
  • クラス>=4（128B以上）の SLL リフィル時に carve する個数の上書き（既定: max_take または余力）。
  • 例: 32/64/96 でA/B。SLLが枯渇しにくくなり、refill頻度が下がる可能性あり。

Alloc側 remote ヘッド読みの緩和（A/B）

• HAKMEM_TINY_ALLOC_REMOTE_RELAX=0/1
  • hak_tiny_alloc_superslab() で remote_heads[slab_idx] 非ゼロチェックを relaxed 読みで実施（既定は acquire）。
  • 所有権獲得→drain の順序は保持されるため安全。分岐率の低下・ロード圧の軽減を狙うA/B用。

Front リフィル量（A/B）

• HAKMEM_TINY_REFILL_COUNT=N（全クラス共通）
• HAKMEM_TINY_REFILL_COUNT_HOT=N（class<=3）
• HAKMEM_TINY_REFILL_COUNT_MID=N（class>=4）
• HAKMEM_TINY_REFILL_COUNT_C{0..7}=N（クラス個別）
  • tiny_alloc_fast のリフィル数を制御（既定16）。大きくするとミス頻度が下がる一方、1回のリフィルコストは増える。

重要: publish/adopt の前提（SuperSlab ON）

• HAKMEM_TINY_USE_SUPERSLAB=1
  • publish→mailbox→adopt のパイプラインは SuperSlab 経路が ON のときのみ動作します。
  • ベンチでは既定ONを推奨（A/BでOFFにしてメモリ効率重視の比較も可能）。
  • OFF の場合、[Publish Pipeline]/[Publish Hits] は 0 のままとなります。

SuperSlab cache / precharge（Phase 6.24+）

• HAKMEM_TINY_SS_CACHE=N
  • クラス共通の SuperSlab キャッシュ上限（per-class の保持枚数）。0=無制限、未指定=無効。
  • キャッシュ有効時は superslab_free() が空の SuperSlab を即 munmap せず、キャッシュに積んで再利用する。
• HAKMEM_TINY_SS_CACHE_C{0..7}=N
  • クラス別のキャッシュ上限（個別指定）。指定があるクラスは HAKMEM_TINY_SS_CACHE より優先。
• HAKMEM_TINY_SS_PRECHARGE=N
  • Tiny クラスごとに N 枚の SuperSlab を事前確保し、キャッシュにプールする。0=無効。
  • 事前確保した SuperSlab は MAP_POPULATE 相当で先読みされ、初回アクセス時の PF を抑制。
  • 指定すると自動的にキャッシュも有効化される（precharge 分を保持するため）。
• HAKMEM_TINY_SS_PRECHARGE_C{0..7}=N
  • クラス別の precharge 枚数（個別上書き）。例: 8B クラスのみ 4 枚プリチャージ → HAKMEM_TINY_SS_PRECHARGE_C0=4
• HAKMEM_TINY_SS_POPULATE_ONCE=1
  • 次回 mmap で取得する SuperSlab を 1 回だけ MAP_POPULATE で fault-in（A/B 用のワンショットプリタッチ）。

Harvest / Guard（mmap前の収穫ゲート）

• HAKMEM_TINY_SS_CAP=N
  • Tiny 各クラスにおける SuperSlab 上限（0=無制限）。
• HAKMEM_TINY_SS_CAP_C{0..7}=N
  • クラス別上限の個別指定（0=無制限）。
• HAKMEM_TINY_GLOBAL_WATERMARK_MB=MB
  • 総確保バイト数がしきい値（MB）を超えた場合にハーベストを強制（0=無効）。

Counters（ダンプ）

• HAKMEM_TINY_COUNTERS_DUMP=1
  • 拡張カウンタを標準エラーにダンプ（クラス別）。
  • SS adopt/publish に加えて、Slab adopt/publish/requeue/miss を出力。
  • [Publish Pipeline]: notify_calls / same_empty_pubs / remote_transitions / mailbox_reg_calls / mailbox_slow_disc
• [Free Pipeline]: ss_local / ss_remote / tls_sll / magazine

Safety (free の検証)

• HAKMEM_SAFE_FREE=1
  • free 境界で追加の検証を有効化（SuperSlab 範囲・クラス不一致・危険な二重 free の検出）。
  • デバッグ時の既定推奨。perf 計測時は 0 を推奨。

P2 TLS SLL Redesign (Header/Next conflict fix)

• HAKMEM_TINY_ACTIVE_TRACK=1
  • meta->active / meta->tls_cached tracking を有効化。
  • active: ユーザが保持中のブロック数
  • tls_cached: TLS SLL にキャッシュされたブロック数
  • Invariant: active + tls_cached ≈ used
  • 有効時、ss_is_slab_empty() は active==0 で EMPTY 判定（TLS SLL のキャッシュも考慮）。
  • オーバーヘッド: 約1%（atomic inc/dec per alloc/free）。
• HAKMEM_TINY_NO_CLASS_MAP=1
  • class_map ルックアップを無効化（legacy mode）。
  • 既定: class_map ON（P2.1 で default 化）。
  • Header から class_idx を読む従来動作に戻す（Header/Next 競合リスクあり）。
• HAKMEM_TINY_RESTORE_HEADER=1
  • tiny_next_store() で Header 復元を強制（legacy mode）。
  • 既定: Header 復元 OFF（P2.3 で無効化）。
  • class_map 使用時は Header 復元不要（alloc 時に HAK_RET_ALLOC で書き直される）。
• HAKMEM_TINY_INVARIANT_CHECK=1
  • active + tls_cached ≈ used の不変条件検証を有効化（debug builds）。
  • 違反時は stderr に警告出力（NDEBUG 未定義時のみ）。
  • オーバーヘッド: 約2%（ss_verify_superslab_invariants() 呼び出し時のみ）。
• HAKMEM_TINY_INVARIANT_DUMP=1
  • スラブ状態の定期ダンプを有効化（debug builds, NDEBUG 未定義時のみ）。
  • used/active/tls_cached/capacity/class の内訳を stderr に出力。

Frontend (mimalloc-inspired, experimental)

• HAKMEM_INT_ADAPT_REFILL=0/1
  • INTで refill 上限（HAKMEM_TINY_REFILL_MAX(_HOT)）をウィンドウ毎に±16で調整（既定ON）
• HAKMEM_INT_ADAPT_CAPS=0/1
  • INTでクラス別 MAG/SLL 上限を軽く調整（±16/±32）。熱いクラスは上限を少し広げ、低頻度なら縮小（既定ON）

Other useful

New (debug isolation)

• HAKMEM_TINY_DISABLE_READY=0/1
  • Ready/Mailboxのコンシューマ経路を完全停止（既定0=ON）。TSan/ASanの隔離実験でSS+freelistのみを通す用途。
• HAKMEM_DEBUG_SEGV=0/1
  • 早期SIGSEGVハンドラを登録し、stderrへバックトレースを1回だけ出力（環境により未出力のことあり）。
• HAKMEM_FORCE_LIBC_ALLOC_INIT=0/1
  • プロセス起動～hak_init()完了までの期間だけ、malloc/free を libc へ強制ルーティング（初期化中の dlsym→malloc 再帰や TLS 未初期化アクセスを回避）。init 完了後は自動で通常経路に戻る（env が設定されていても、init 後は無効化される動作）。
• HAKMEM_TINY_MAG_CAP=N
  • TLSマガジンの上限（通常パスのチューニングに使用）
• HAKMEM_TINY_MAG_CAP_C{0..7}=N
  • クラス別のTLSマガジン上限（通常パス）。指定時はクラスごとの既定値を上書き（例: 64B=class3 に 512 を指定）
• HAKMEM_TINY_TLS_SLL=0/1
  • 通常パスのSLLをON/OFF
• HAKMEM_TINY_SLL_CAP_C{0..7}=N
  • 通常パスのクラス別SLL上限（絶対値）。指定時は倍率計算をバイパス
• HAKMEM_TINY_REFILL_MAX=N
  • マガジン低水位時の一括補充上限（既定64）。大きくすると補充回数が減るが瞬間メモリ圧は増える
• HAKMEM_TINY_REFILL_MAX_HOT=N
  • 8/16/32/64Bクラス（class<=3）向けの上位上限（既定192）。小サイズ帯のピーク探索用
• HAKMEM_TINY_REFILL_MAX_C{0..7}=N（新）
  • クラス別の補充上限（個別上書き）。設定があるクラスのみ有効（0=未設定）
• HAKMEM_TINY_REFILL_MAX_HOT_C{0..7}=N（新）
  • ホットクラス（0..3）用の個別上書き。設定がある場合は REFILL_MAX_HOT より優先
• (削除済み) HAKMEM_TINY_BG_REMOTE*
  • 2025-12 cleanup: BG Remote系ENVは廃止（BGリモートは固定OFF）。
• HAKMEM_TINY_REFILL_COUNT=N（ULTRA_SIMPLE用）
  • ULTRA_SIMPLE の SLL リフィル個数（既定 32、8–256）。
• HAKMEM_TINY_FLUSH_ON_EXIT=0/1
  • 退出時にTinyマガジンをフラッシュ＋トリム（RSS計測用）
• HAKMEM_TINY_RSS_BUDGET_KB=N（新）
  • INTエンジン起動時にTinyのRSS予算（kB）を設定。超過時にクラス別のMAG/SLL上限を段階的に縮小（メモリ優先）。
• HAKMEM_TINY_INT_TIGHT=0/1（新）
  • INTの調整を縮小側にバイアス（閾値を上げ、MAG/SLLの最小値を床に近づける）。
• HAKMEM_TINY_DIET_STEP=N（新, 既定16）
  • 予算超過時の一回あたり縮小量（MAG: step, SLL: step×2）。
• HAKMEM_TINY_CAP_FLOOR_C{0..7}=N（新）
  • クラス別MAGの下限（例: C0=64, C3=128）。INTの縮小時にこれ未満まで下げない。
• HAKMEM_DEBUG_COUNTERS=0/1
  • パス/Ultraのデバッグカウンタをビルドに含める（既定0=除去）。ONで HAKMEM_TINY_PATH_DEBUG=1 時に atexit ダンプ。
• HAKMEM_ENABLE_STATS
  • 定義時のみホットパスで stats_record_alloc/free を実行。未定義時は完全に呼ばれない（ベンチ最小化）。
• HAKMEM_TINY_TRACE_RING=1
  • Tiny Debug Ring を有効化。SIGUSR2 またはクラッシュ時に直近4096件の alloc/free/publish/remote イベントを stderr ダンプ。
• HAKMEM_TINY_STAT_SAMPLING（ビルド定義, 任意）/ HAKMEM_TINY_STAT_RATE_LG（環境, 任意）
  • 統計が有効な場合でも、alloc側の統計更新を低頻度化（例: RATE_LG=14 → 16384回に1回）。
  • 既定はOFF（サンプリング無し＝毎回更新）。ベンチ用にONで命令数を削減可能。
• HAKMEM_TINY_HOTMAG=0/1
  • 小クラス用の小型TLSマガジン（128要素, classes 0..3）を有効化。既定0（A/B用）。
  • alloc: HotMag→SLL→Magazine の順でヒットを狙う。free: SLL優先、溢れ時にHotMag→Magazine。

USDT/tracepoints（perfのユーザ空間静的トレース）

• ビルド時に CFLAGS+=-DHAKMEM_USDT=1 を付与すると、主要分岐にUSDT（DTrace互換）プローブが埋め込まれます。
  • 依存: <sys/sdt.h>（Debian/Ubuntu: sudo apt-get install systemtap-sdt-dev）。
  • プローブ名（provider=hakmem）例:
    • sll_pop, mag_pop, front_pop（allocホットパス）
    • bump_hit（TLSバンプシャドウ命中）
    • slow_alloc（スローパス突入）
  • 使い方（例）:
    • 一覧: perf list 'sdt:hakmem:*'
    • 集計: perf stat -e sdt:hakmem:front_pop,cycles ./bench_tiny_hot_hakmem 32 100 40000
    • 記録: perf record -e sdt:hakmem:sll_pop -e sdt:hakmem:mag_pop ./bench_tiny_hot_hakmem 32 100 50000
  • 権限/環境の注意:
    • unknown tracepoint → perfがUSDT（sdt:）非対応、または古いツール。sudo apt-get install linux-tools-$(uname -r) を推奨。
    • can't access trace events → tracefs権限不足。
      • sudo mount -t tracefs -o mode=755 nodev /sys/kernel/tracing
      • sudo sysctl kernel.perf_event_paranoid=1
  • WSLなど一部カーネルでは UPROBE/USDT が無効な場合があります（PMUのみにフォールバック）。

ビルドプリセット（Tiny‑Hot最短フロント）

• コンパイル時フラグ: -DHAKMEM_TINY_MINIMAL_FRONT=1
  • 入口から UltraFront/Quick/Frontend/HotMag/SuperSlab try/BumpShadow を物理的に除去
  • 残る経路: SLL → TLS Magazine → SuperSlab →（以降のスローパス）
  • Makefileターゲット: make bench_tiny_front
    • ベンチと相性の悪い分岐を取り除き、命令列を短縮（PGOと併用推奨）
    • 付与フラグ: -DHAKMEM_TINY_MAG_OWNER=0（マガジン項目のowner書き込みを省略し、alloc/freeの書込み負荷を削減）
• 実行時スイッチ（軽量A/B）: HAKMEM_TINY_MINIMAL_HOT=1
  • 入口で SuperSlab TLSバンプ→SuperSlab直経路を優先（ビルド除去ではなく分岐）
  • Tiny‑Hotでは概ね不利（命令・分岐増）なため、既定OFF。ベンチA/B用途のみ。

Scripts

• scripts/run_tiny_hot_triad.sh
• scripts/run_tiny_benchfast_triad.sh — bench-only fast path triad
• scripts/run_tiny_sllonly_triad.sh — SLL-only + warmup + PGO triad
• scripts/run_tiny_sllonly_r12w192_triad.sh — SLL-only tuned（32B: REFILL=12, WARMUP32=192）
• scripts/run_ultra_debug_sweep.sh
• scripts/sweep_ultra_params.sh <bench_batch>
• scripts/run_comprehensive_pair.sh
• scripts/run_random_mixed_matrix.sh

Bench-only build flags (compile-time)

• HAKMEM_TINY_BENCH_FASTPATH=1 — 入口を SLL→Mag→tiny refill に固定（最短パス）
• HAKMEM_TINY_BENCH_SLL_ONLY=1 — Mag を物理的に除去（SLL-only）、freeもSLLに直push
• HAKMEM_TINY_BENCH_TINY_CLASSES=3 — 対象クラス（0..N, 3→≤64B）
• HAKMEM_TINY_BENCH_WARMUP8/16/32/64 — 初回ウォームアップ個数（例: 32=160〜192）
• HAKMEM_TINY_BENCH_REFILL/REFILL8/16/32/64 — リフィル個数（例: REFILL32=12）

Makefile helpers

• bench_fastpath / pgo-benchfast-* — bench_fastpathのPGO
• bench_sll_only / pgo-benchsll-* — SLL-onlyのPGO
• pgo-benchsll-r12w192-* — 32Bに合わせたREFILL/WARMUPのPGO

Perf‑Main preset（メインライン向け、安全寄り, opt‑in）

• 推奨環境変数（例）:
  • HAKMEM_TINY_TLS_SLL=1
  • HAKMEM_TINY_REFILL_MAX=96
  • HAKMEM_TINY_REFILL_MAX_HOT=192
  • HAKMEM_TINY_SPILL_HYST=16
• 実行例:
  • Tiny‑Hot triad: HAKMEM_TINY_TLS_SLL=1 HAKMEM_TINY_REFILL_MAX=96 HAKMEM_TINY_REFILL_MAX_HOT=192 HAKMEM_TINY_SPILL_HYST=16 bash scripts/run_tiny_hot_triad.sh 60000
  • Random‑Mixed: HAKMEM_TINY_TLS_SLL=1 HAKMEM_TINY_REFILL_MAX=96 HAKMEM_TINY_REFILL_MAX_HOT=192 HAKMEM_TINY_SPILL_HYST=16 bash scripts/run_random_mixed_matrix.sh 100000

LD safety (for apps/LD_PRELOAD runs)

• HAKMEM_LD_SAFE=0/1/2
  • 0: full (開発用のみ推奨)
  • 1: Tinyのみ（非Tinyはlibcへ委譲）
  • 2: パススルー（推奨デフォルト）
• HAKMEM_TINY_SPECIALIZE_8_16=0/1（新）
  • 8/16B向けに“mag-popのみ”の特化経路を有効化（既定OFF）。A/B用。
• HAKMEM_TINY_SPECIALIZE_32_64=0/1
  • 32/64B向けに“mag-popのみ”の特化経路を有効化（既定OFF）。A/B用。
• HAKMEM_TINY_SPECIALIZE_MASK=（新）
  • クラス別に特化を有効化するビットマスク（bit0=8B, bit1=16B, …, bit7=64B）。
  • 例: 0x02 → 16Bのみ特化、0x0C → 32/64B特化。
• HAKMEM_TINY_BENCH_MODE=1
  • ベンチ専用の簡素化採用パスを有効化。per-class 単一点の公開スロットを使用し、superslab_refill のスキャンと多段リング走査を回避。
  • OOMガード（harvest/trim）は保持。A/B用途に限定してください。

---

ENV Cleanup Progress (2025-11)

Phase 4a: Hot Path getenv Caching

COMPLETED: All getenv() calls in hot paths are now properly cached.

Fixed files:

• core/hakmem_elo.c - Added is_quiet() helper with cached g_quiet_mode flag
  • Was: 10+ getenv("HAKMEM_QUIET") calls inside loops
  • Now: Single cached lookup at first call

Verified (already correct):

• core/hakmem_tiny_superslab.c - Uses static int g_* caching pattern
• core/hakmem_shared_pool.c - Uses static int xxx = -1 caching
• core/hakmem_learner.c - getenv outside main loop (thread start only)
• core/box/pool_init_api.inc.h - Init function (called once via pthread_once)
• core/box/hak_core_init.inc.h - Init function (called once via pthread_once)
• core/box/hak_wrappers.inc.h - Uses static int on=-1 caching

ENV Statistics (from ENV_VARIABLE_SURVEY.md):

• Total ENV variables: 228
• Target after cleanup: ~80 (65% reduction)
• Categories:
  • Core/Toggle: 15 (7%)
  • Learning/Adaptive: 25 (11%)
  • Performance Tuning: 45 (20%)
  • Debug/Diagnostic: 65 (28%) ← Consolidation target
  • Superslab/Backend: 25 (11%)
  • TLS SLL (P2/P3): 20 (9%)
  • Free Path Optimization: 15 (7%)
  • Other: 23 (10%)

Phase 4b: Master Debug Control (COMPLETED)

New in 2025-11: Centralized debug control that works alongside individual module ENVs.

• HAKMEM_DEBUG_ALL=1

  • Enable ALL debug modules at once (convenient for troubleshooting)
  • Individual module ENVs (e.g., HAKMEM_SFC_DEBUG=0) can still override

• HAKMEM_DEBUG_LEVEL=N

  • Set debug level: 0=off, 1=critical, 2=normal, 3=verbose
  • When set to 2+, enables debug output for modules that don't have explicit ENV

• HAKMEM_QUIET=1

  • Suppress ALL debug output (highest priority, overrides DEBUG_ALL/LEVEL)

Priority order:

1. HAKMEM_QUIET=1 → suppress all
2. Specific module ENV (e.g., HAKMEM_SFC_DEBUG=1) → use that value
3. HAKMEM_DEBUG_ALL=1 → enable all
4. HAKMEM_DEBUG_LEVEL >= threshold → enable
5. Default → disabled

Implementation: core/hakmem_debug_master.h

• hak_debug_check("HAKMEM_FOO_DEBUG") - Check if module should enable debug
• hak_is_quiet() - Quick check for quiet mode

Phase 4c: Master Trace Control (COMPLETED)

New in 2025-11: Unified trace control.

• HAKMEM_TRACE=all

  • Enable ALL trace modules at once

• HAKMEM_TRACE=ptr,refill,free,mailbox

  • Enable specific trace modules (comma-separated)

• HAKMEM_TRACE_LEVEL=N

  • Set trace verbosity (1=basic, 2=detailed, 3=verbose)

Available trace modules: ptr, refill, superslab, ring, free, mailbox, registry

Implementation: core/hakmem_trace_master.h

Phase 4d: Master Stats Control (COMPLETED)

New in 2025-11: Unified stats/dump control.

• HAKMEM_STATS=all

  • Enable ALL stats modules at once

• HAKMEM_STATS=sfc,fast,pool

  • Enable specific stats modules (comma-separated)

• HAKMEM_STATS_DUMP=1

  • Dump stats at process exit

Available stats modules: sfc, fast, heap, refill, counters, ring, invariant, pagefault, front, pool, slim, guard, nearempty

Implementation: core/hakmem_stats_master.h

---

ENV Cleanup Summary (2025-11)

• Phase 4a: Hot path getenv caching (hakmem_elo.c fixed)
• Phase 4b: HAKMEM_DEBUG_ALL/LEVEL master debug control
• Phase 4c: HAKMEM_TRACE unified trace control
• Phase 4d: HAKMEM_STATS unified stats control

Total new master control variables: 6 HAKMEM_DEBUG_ALL, HAKMEM_DEBUG_LEVEL HAKMEM_TRACE, HAKMEM_TRACE_LEVEL HAKMEM_STATS, HAKMEM_STATS_DUMP

All existing individual ENVs continue to work (backwards compatible)

---

Benchmark Environment Variables (2025-11-29)

HAKMEM_BENCH_FAST_FRONT

Enable ultra-fast header-based free path for benchmarks.

• Default: 0 (OFF)
• Usage: HAKMEM_BENCH_FAST_FRONT=1 ./bench_random_mixed_hakmem
• Effect: Tries hak_tiny_free_fast_v2() before normal free path
• Location: core/box/hak_free_api.inc.h:98-114
• A/B Testing: Compare throughput with/without this flag

HAKMEM_BENCH_WARMUP

Number of warmup cycles before timed benchmark run.

• Default: 0 (no warmup)
• Usage: HAKMEM_BENCH_WARMUP=1000000 ./bench_random_mixed_hakmem
• Effect: Runs N allocation cycles (not timed) before starting benchmark
• Purpose: Warm up TLS caches, SuperSlabs, and system allocator
• Location: bench_random_mixed.c:69-92

HAKMEM_FREE_ROUTE_TRACE

Debug trace for free() routing decisions.

• Default: 0 (OFF)
• Usage: HAKMEM_FREE_ROUTE_TRACE=1 ./bench_random_mixed_hakmem
• Effect: Logs first 32 free() routing decisions (tiny/pool/mid/external)
• Output: [FREE_ROUTE] <domain> ptr=<addr>
• Location: core/box/hak_free_api.inc.h:17-40
• Use case: Debug which Box handles each free()

HAKMEM_EXTERNAL_GUARD_LOG

Enable ExternalGuard debug logging.

• Default: 0 (OFF)
• Usage: HAKMEM_EXTERNAL_GUARD_LOG=1 ./bench
• Effect: Logs all ExternalGuard calls with ptr info, SuperSlab lookup, FrontGate classification
• Location: core/box/external_guard_box.h:40-48
• Use case: Debug unknown pointers that reach ExternalGuard

HAKMEM_EXTERNAL_GUARD_STATS

Print ExternalGuard statistics at exit.

• Default: 0 (OFF)
• Usage: HAKMEM_EXTERNAL_GUARD_STATS=1 ./bench
• Output: Total calls, unknown ptrs, etc.
• Location: core/box/external_guard_box.h:140-162

---

Build Flags (Compile-time, set via Makefile)

HAKMEM_TINY_SS_TRUST_MMAP_ZERO

Skip large memset() for fresh mmap SuperSlabs (trust OS zero pages).

• Default: 0 (defensive memset enabled)
• Build: HAKMEM_TINY_SS_TRUST_MMAP_ZERO=1 make bench_random_mixed_hakmem
  • Or: EXTRA_MAKEFLAGS="HAKMEM_TINY_SS_TRUST_MMAP_ZERO=1" ./build.sh release bench_random_mixed_hakmem
• Effect:
  • When =1 AND release build AND fresh mmap (not from cache):
    • Skip memset for slabs/remote_heads/remote_counts/slab_listed arrays
    • Still memset class_map to 255 (UNASSIGNED)
  • Cache reuse (from_cache=1): Always full memset (defensive)
• Performance: +5.93% on bench_tiny_hot, neutral on bench_random_mixed
• Safety: Only activates in release builds; cache reuse always gets full memset
• Location:
  • Flag definition: core/hakmem_build_flags.h:170-180
  • Implementation: core/box/ss_allocation_box.c:37-78
• A/B Testing: Compare fresh SuperSlab allocation throughput
• Recommendation: Keep default=0 for safety; enable for production after testing

HAKMEM_DISABLE_MINCORE_CHECK (REMOVED in Phase 3)

DEPRECATED: Removed in commit d78baf41c (Phase 3: Remove mincore() syscall completely)

• Previously controlled mincore() syscall in free path
• Now always disabled (trust internal metadata)
• See: CHECKPOINT_PHASE2_COMPLETE.md, PHASE2_PERF_ANALYSIS.md

---

Update History:

• 2025-11-29: Added benchmark env vars (BENCH_FAST_FRONT, BENCH_WARMUP, FREE_ROUTE_TRACE)
• 2025-11-29: Added HAKMEM_TINY_SS_TRUST_MMAP_ZERO build flag
• 2025-11-29: Marked DISABLE_MINCORE_CHECK as removed