# Allocator Comparison SSOT（system / jemalloc / mimalloc / tcmalloc）

目的: hakmem の「速さ以外の勝ち筋」（syscall budget / 安定性 / 長時間）を崩さず、外部 allocator との比較を再現可能に行う。

## 原則

- **同一バイナリ A/B（ENVトグル）**は性能最適化の SSOT（layout tax 回避）。
- allocator 間比較（mimalloc/jemalloc/tcmalloc/system）は **別バイナリ/LD_PRELOAD**が混ざるため、**reference**として扱う。
- 参照値は **環境ドリフト**が起きるので、`docs/analysis/PERFORMANCE_TARGETS_SCORECARD.md` の snapshot を正とし、定期的に rebase する。
- 短い比較（長時間 soak なし）の手順: `docs/analysis/ALLOCATOR_COMPARISON_QUICK_RUNBOOK.md`

## 1) ベンチ（シナリオ型, 単体プロセス）

### ビルド

```bash
make bench
```

生成物:
- `./bench_allocators_hakmem`（hakmem linked）
- `./bench_allocators_system`（system malloc, LD_PRELOAD 用）

### 実行（CSV出力）

```bash
scripts/bench_allocators_compare.sh --scenario mixed --iterations 50
```

注記:
- `bench_allocators_*` の `--scenario mixed` は 8B..1MB の簡易ワークロード（small-scale reference）。
- Mixed 16–1024B SSOT（`scripts/run_mixed_10_cleanenv.sh`）とは別物なので、数値を混同しないこと。

環境変数（任意）:
- `JEMALLOC_SO=/path/to/libjemalloc.so.2`
- `MIMALLOC_SO=/path/to/libmimalloc.so.2`
- `TCMALLOC_SO=/path/to/libtcmalloc.so` または `libtcmalloc_minimal.so`

出力形式（1行CSV）:
`allocator,scenario,iterations,avg_ns,soft_pf,hard_pf,rss_kb,ops_per_sec`

補足:
- `rss_kb` は `getrusage(RUSAGE_SELF).ru_maxrss` をそのまま出している（Linux では KB）。

## 2) TCMalloc（gperftools）をローカルで用意する

システムに tcmalloc が無い場合:

```bash
scripts/setup_tcmalloc_gperftools.sh
export TCMALLOC_SO="$PWD/deps/gperftools/install/lib/libtcmalloc.so"
```

注意:
- `autoconf/automake/libtool` が必要な環境があります（ビルド失敗時は不足パッケージを入れる）。
- これは **比較用の補助**であり、hakmem の本線ビルドを変更しない。

## 3) 運用メトリクス（soak / stability）

hakmem の運用勝ち筋を比較する SSOT は以下:
- `docs/analysis/PHASE50_OPERATIONAL_EDGE_STABILITY_SUITE_RESULTS.md`
- `docs/analysis/PHASE51_SINGLE_PROCESS_SOAK_AND_TAIL_PLAN_RESULTS.md`

短時間（5分）:
- `scripts/soak_mixed_rss.sh`
- `scripts/soak_mixed_single_process.sh`

## 4) Scorecard への反映

- 参照値（jemalloc/mimalloc/system/tcmalloc）は `docs/analysis/PERFORMANCE_TARGETS_SCORECARD.md` の
  **Reference allocators** に追記する。
- 比較の意味付けは「速さ」だけでなく:
  - `syscalls/op`
  - `RSS drift`
  - `CV`
  - `tail proxy（p99/p50）`
  を含めて整理する。

## 5) layout tax 対策（重要）

allocator 間比較で「hakmem だけ遅い/速い」が極端に出た場合、まず **同一バイナリでの比較**を行う:

- `bench_random_mixed_system` を固定し、`LD_PRELOAD` で allocator を差し替える（apples-to-apples）
- runner: `scripts/run_allocator_preload_matrix.sh`

この比較は “reference の中でも最も公平” なので、SCORECARD に記録する場合は優先する。

### 重要: 「同一バイナリ比較」と「hakmem SSOT（linked）」は別物

`LD_PRELOAD` 比較は「drop-in malloc」としての比較（全 allocator が同じ入口を通る）であり、
hakmem の SSOT（`bench_random_mixed_hakmem*` を `scripts/run_mixed_10_cleanenv.sh` で回す）とは経路が異なる。

- `bench_random_mixed_hakmem*`: hakmem のプロファイル/箱構造を前提にした SSOT（最適化判断の正）
- `bench_random_mixed_system` + `LD_PRELOAD=./libhakmem.so`: drop-in wrapper としての reference（layout差を抑えられるが、wrapper税は含む）

“hakmemが遅くなった/速くなった” の議論では、どちらの測り方かを必ず明記すること。