hakmem/docs/specs/ENV_VARS.md

ENV Vars (Runtime Controls)

学習・キャッシュ・ラッパー挙動などのランタイム制御一覧です。

学習（CAP / 窓 / 予算）

• HAKMEM_LEARN=1 — CAP学習ON（別スレッド）
• HAKMEM_LEARN_WINDOW_MS — 学習窓（既定 1000ms）
• HAKMEM_TARGET_HIT_MID / HAKMEM_TARGET_HIT_LARGE — 目標ヒット率（既定 0.65 / 0.55）
• HAKMEM_CAP_STEP_MID / HAKMEM_CAP_STEP_LARGE — CAPの更新ステップ（既定 4 / 1）
• HAKMEM_BUDGET_MID / HAKMEM_BUDGET_LARGE — 合計CAPの上限（0=無効）

Mid/Large CAP手動上書き

• HAKMEM_CAP_MID=a,b,c,d,e — 2/4/8/16/32KiB のCAP（ページ）
• HAKMEM_CAP_LARGE=a,b,c,d,e — 64/128/256/512KiB/1MiB のCAP（バンドル）

可変Midクラス（DYN1）

• HAKMEM_MID_DYN1=<bytes> — 可変クラス1枠を有効化（例: 14336）
• HAKMEM_CAP_MID_DYN1=<pages> — DYN1専用CAP
• HAKMEM_DYN1_AUTO=1 — サイズ分布ピークから自動割り当て（固定クラスと衝突しない場合のみ）
• HAKMEM_HIST_SAMPLE=N — サイズ分布のサンプリング（2^N に1回）

ラッパー挙動（LD_PRELOAD）

• HAKMEM_WRAP_L2=1 / HAKMEM_WRAP_L25=1 — ラッパー内でもMid/L2.5使用を許可（安全に留意）
• HAKMEM_POOL_TLS_FREE=0/1 — Mid free をTLS返却（1=既定）
• HAKMEM_POOL_MIN_BUNDLE=<n> — Mid補充の最小バンドル（既定2）
• HAKMEM_POOL_REFILL_BATCH=1-4 — Phase 6.25: Mid Pool refill 時のページ batch 数（既定2、1=batch無効）
• HAKMEM_WRAP_TINY=1 — ラッパー内でもTinyを許可（magazineのみ/ロック回避）
• HAKMEM_WRAP_TINY_REFILL=1 — ラッパー内で小規模trylockリフィル許可（安全性優先で既定OFF）

丸め許容（W_MAX）

• HAKMEM_WMAX_MID / HAKMEM_WMAX_LARGE — 丸め許容（例: 1.4）
• HAKMEM_WMAX_LEARN=1 — W_MAX学習ON（簡易: ラウンドロビン）
• HAKMEM_WMAX_CANDIDATES_MID / HAKMEM_WMAX_CANDIDATES_LARGE — 候補（例: "1.4,1.6,1.7"）
• HAKMEM_WMAX_DWELL_SEC — 候補切替の最小保持秒数（既定10）

プロファイル

• HAKMEM_PROF=1 / HAKMEM_PROF_SAMPLE=N — 軽量サンプリング・プロファイラ
• HAKMEM_ACE_SAMPLE=N — L1ヒット/ミス/L1フォールバックのサンプル率

カウンタのサンプリング（ホットパス書込みの削減）

• HAKMEM_POOL_COUNT_SAMPLE=N — Midのhits/misses/freesを2^Nに1回だけ更新（既定10=1/1024）
• HAKMEM_TINY_COUNT_SAMPLE=N — Tinyのalloc/freeカウントを2^Nに1回だけ更新（既定8=1/256）

セーフティ

• HAKMEM_SAFE_FREE=1 — free時 mincore ガード（オーバーヘッド注意）

Mid TLS 二段（リング+ローカルLIFO）

• HAKMEM_POOL_TLS_RING=0/1 — TLSリング有効化（既定1）
• HAKMEM_TRYLOCK_PROBES=K — 非空シャードへのtrylock試行回数（既定3）
• HAKMEM_RING_RETURN_DIV=2|3|4 — リング満杯時の吐き戻し率（2=1/2, 3=1/3）
• HAKMEM_TLS_LO_MAX=<n> — TLSローカルLIFOの上限（既定256）
• HAKMEM_SHARD_MIX=1 — site→shardの分散ハッシュを強化（splitmix64）

L2.5（LargePool）専用

• HAKMEM_L25_RUN_BLOCKS=<n> — bump-runのブロック数を上書き（クラス共通）。既定はクラス別に約2MiB/ラン（64KB:32, 128KB:16, 256KB:8, 512KB:4, 1MB:2）
• HAKMEM_L25_RUN_FACTOR=<n> — ラン長の倍率（1..8）。RUN_BLOCKS 指定時は無効
• HAKMEM_L25_PREF=remote|run — TLSミス時の順序。remote=リモートドレイン優先、run=bump-run優先（既定: remote）
• HAKMEM_WRAP_L25=0/1 — ラッパー内でもL2.5使用を許可（既定0）
• HAKMEM_L25_TC_SPILL=<n> — free時のTransfer Cacheスピル閾値（既定32、0=無効）
• HAKMEM_L25_BG_DRAIN=0/1 — BGスレッドで remote→freelist を定期ドレイン（既定0）
• HAKMEM_L25_BG_MS=<n> — BGドレイン間隔（ミリ秒, 既定5）
• HAKMEM_L25_TC_CAP=<n> — TCリング容量（既定64, 8..64）
• HAKMEM_L25_RING_TRIGGER=<n> — remote-firstの起動トリガ（リング残がn以下の時だけ、既定2）
• HAKMEM_L25_OWNER_INBOUND=0/1 — owner直帰モード（cross‑thread freeはページownerのinboundへ積む）。allocは自分のinboundから少量drainしてTLSへ
• HAKMEM_L25_INBOUND_SLOTS=<n> — inboundスロット数（既定512, 128..2048 目安）。ビルド既定より大きい値は切り捨て

ログ抑制

• HAKMEM_INVALID_FREE_LOG=0/1 — 無効freeログ出力のON/OFF（既定0=抑制）

注: 上記の TLS/RING/PROBES/LO_MAX は L2.5（LargePool）にも適用されます（同名ENVで連動）。

バッチ系（madvise/munmap のバックグラウンド化）

• HAKMEM_BATCH_BG=0/1 — バックグラウンドスレッドでバッチをフラッシュ（既定1=ON）
  • 大きな解放（>=64KiB）は hak_batch_add() に蓄積→しきい値到達/定期でBGが flush
  • ホットパスから madvise/munmap を外し、TLBフラッシュ/システムコールをBGへ移譲

タイミング計測（Debug Timing）

• HAKMEM_TIMING=1 — カテゴリ別の集計をstderrにダンプ（終了時）
  • 主要カテゴリ（抜粋）:
    • Mid(L2): pool_lock, pool_refill, pool_tc_drain, pool_tls_ring_pop, pool_tls_lifo_pop, pool_remote_push, pool_alloc_tls_page
    • L2.5: l25_lock, l25_refill, l25_tls_ring_pop, l25_tls_lifo_pop, l25_remote_push, l25_alloc_tls_page, l25_shard_steal
  • 使い方（例）:
    • HAKMEM_TIMING=1 LD_PRELOAD=./libhakmem.so mimalloc-bench/bench/larson/larson 10 65536 1048576 10000 1 12345 4

Mid Transfer Cache（TC）

• HAKMEM_TC_ENABLE=0/1 — TCを有効化（既定1）
• HAKMEM_TC_UNBOUNDED=0/1 — ドレイン個数の上限を無効化（既定1）
• HAKMEM_TC_DRAIN_MAX=<n> — 1回のallocでドレインする最大個数（既定64程度、0で無制限）
• HAKMEM_TC_DRAIN_TRIGGER=<n> — リング残量がn未満のときのみドレイン（既定2）

MF2: Per-Page Sharding（Phase 7.2）

• HAKMEM_MF2_ENABLE=0/1 — MF2 Per-Page Sharding有効化（既定0=無効）
  • mimalloc方式: 各64KBページが独立したfreelistを保持、O(1)ページ検索
  • 期待性能: Mid 4T +50% (13.78 → 20.7 M/s)

ビルド時（Makefile）

• RING_CAP=<8|16|32> — TLSリング容量（Mid）。make shared RING_CAP=16 など

しきい値（mmap）

• HAKMEM_THP_LEARN=1（将来）/ thp_threshold は FrozenPolicy 側に保持（既定 2MiB）

ヘッダ書込み（Mid, 実験的）

• HAKMEM_HDR_LIGHT=0|1|2
  • 0: フルヘッダ（magic/method/size/alloc_site/class_bytes/owner_tid）
  • 1: 最小ヘッダ（magic/method/size のみ。owner未設定）
  • 2: ヘッダ書込み/検証スキップ（危険。ページ記述子の所有者判定と併用前提）