Debug Counters Implementation - Clean History
Major Features: - Debug counter infrastructure for Refill Stage tracking - Free Pipeline counters (ss_local, ss_remote, tls_sll) - Diagnostic counters for early return analysis - Unified larson.sh benchmark runner with profiles - Phase 6-3 regression analysis documentation Bug Fixes: - Fix SuperSlab disabled by default (HAKMEM_TINY_USE_SUPERSLAB) - Fix profile variable naming consistency - Add .gitignore patterns for large files Performance: - Phase 6-3: 4.79 M ops/s (has OOM risk) - With SuperSlab: 3.13 M ops/s (+19% improvement) This is a clean repository without large log files. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Moe Charm (CI)
35
docs/specs/CURRENT_SPEC.md
Normal file
35
docs/specs/CURRENT_SPEC.md
Normal file
@ -0,0 +1,35 @@
|
||||
# CURRENT SPEC (SACS‑3)
|
||||
|
||||
## Hot Path
|
||||
- サイズでTier決定: Tiny(≤1KiB) / L1 ACE(1KiB–<2MiB) / L2 Big(≥2MiB)
|
||||
- RCUスナップショット `FrozenPolicy` を関数冒頭で1回load、以後読み取りのみ
|
||||
- `clock_gettime()` のような重い処理はホットパス禁止（サンプリングのみ）
|
||||
|
||||
## Layers
|
||||
- Tiny: TLS Magazine + TLS Active Slab + MPSC remote‑free
|
||||
- L1 ACE:
|
||||
- Mid: 2/4/8/16/32 KiB（＋DYN1: 環境で1枠可変）
|
||||
- Large: 64/128/256/512 KiB/1 MiB
|
||||
- W_MAX 丸め: `class ≤ W_MAX × size` のとき上位クラス許可
|
||||
- 32–64KiB ギャップはW_MAXで64KiB吸収
|
||||
- L2 Big: BigCache + mmap（THPゲート）
|
||||
|
||||
## Learning
|
||||
- CAP学習（実装済）
|
||||
- 別スレッドで窓ごとにヒット/ミス差分→ヒット率 vs 目標（Mid 0.65 / Large 0.55）で CAP ±Δ
|
||||
- 予算制約（任意）とヒステリシス
|
||||
- Soft CAPでリフィル強度を調整（Over: bundle=1 / Under: ≤4, 下限はENV）
|
||||
- DYN1（可変Midクラス×1）
|
||||
- `HAKMEM_MID_DYN1=<bytes>` で1枠有効化、ACE候補に追加、Poolは完全一致で判定
|
||||
- DYN1専用CAP: `mid_cap_dyn1`（学習対象）
|
||||
- しきい値（mmap）
|
||||
- `FrozenPolicy.thp_threshold` をホットパスで使用（既定 2MiB）。
|
||||
- 学習（オプション）で離散候補を回し、将来的にUCB1/Canaryで最適化（現状はラウンドロビン採用の簡易版）。
|
||||
|
||||
## ENV（抜粋）
|
||||
- 学習: `HAKMEM_LEARN=1`, `HAKMEM_LEARN_WINDOW_MS`, `HAKMEM_TARGET_HIT_MID/LARGE`, `HAKMEM_CAP_STEP_MID/LARGE`, `HAKMEM_BUDGET_MID/LARGE`
|
||||
- CAP手動: `HAKMEM_CAP_MID=a,b,c,d,e`, `HAKMEM_CAP_LARGE=a,b,c,d,e`, `HAKMEM_CAP_MID_DYN1`
|
||||
- W_MAX: `HAKMEM_WMAX_MID`, `HAKMEM_WMAX_LARGE`
|
||||
- DYN1: `HAKMEM_MID_DYN1=<bytes>`
|
||||
- ラッパー内L1許可: `HAKMEM_WRAP_L2=1`, `HAKMEM_WRAP_L25=1`
|
||||
- Midリフィル最小バンドル: `HAKMEM_POOL_MIN_BUNDLE`（既定2）
|
||||
106
docs/specs/ENV_VARS.md
Normal file
106
docs/specs/ENV_VARS.md
Normal file
@ -0,0 +1,106 @@
|
||||
# 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: ヘッダ書込み/検証スキップ（危険。ページ記述子の所有者判定と併用前提）
|
||||
Reference in New Issue
Block a user