# Allocator Comparison Quick Runbook（長時間 soak なし）

目的: 「まず全体像」を短時間で揃える。最適化判断の SSOT（同一バイナリ A/B）とは別に、外部 allocator の reference を取る。

## 0) 注意（SSOTとreferenceの混同禁止）

- Mixed 16–1024B SSOT: `scripts/run_mixed_10_cleanenv.sh`（hakmem の最適化判断の正）
- allocator比較（jemalloc/tcmalloc/system/mimalloc）は **別バイナリ or LD_PRELOAD** で layout差を含むため **reference**

## 1) 事前準備（1回だけ）

### 1.1 ビルド（比較用バイナリ）

```bash
make bench_random_mixed_hakmem bench_random_mixed_system bench_random_mixed_mi
make bench
```

オプション（FAST PGO も比較したい場合）:
```bash
make pgo-fast-full
```

### 1.2 jemalloc / tcmalloc の .so パス

環境にある場合:
```bash
export JEMALLOC_SO=/path/to/libjemalloc.so.2
export TCMALLOC_SO=/path/to/libtcmalloc.so
```

tcmalloc が無ければ（gperftoolsからローカルビルド）:
```bash
scripts/setup_tcmalloc_gperftools.sh
export TCMALLOC_SO="$PWD/deps/gperftools/install/lib/libtcmalloc.so"
```

## 2) Quick matrix（Random Mixed, 10-run）

長時間 soak なしで「同じベンチ形」の比較を取る（system/jemalloc/tcmalloc/mimalloc/hakmem）。

```bash
ITERS=20000000 WS=400 SEED=1 RUNS=10 scripts/run_allocator_quick_matrix.sh
```

出力:
- 各 allocator の `mean/median/CV/min/max`（M ops/s）

注記:
- hakmem は `HAKMEM_PROFILE` が未指定だと “別ルート” を踏み、数値が大きく壊れることがある。
  `scripts/run_allocator_quick_matrix.sh` は SSOT と同じく `HAKMEM_PROFILE=MIXED_TINYV3_C7_SAFE` を明示する。
- 「同じマシンなのに数値が変わる」切り分け用に、SSOTベンチでは環境ログを出せる:
  - `HAKMEM_BENCH_ENV_LOG=1 RUNS=10 scripts/run_mixed_10_cleanenv.sh`

### 同一バイナリでの比較（推奨）

layout tax を避けたい場合は、`bench_random_mixed_system` を固定して LD_PRELOAD を差す:

```bash
make bench_random_mixed_system shared
export MIMALLOC_SO=/path/to/libmimalloc.so.2   # optional
export JEMALLOC_SO=/path/to/libjemalloc.so.2   # optional
export TCMALLOC_SO=/path/to/libtcmalloc.so     # optional
RUNS=10 scripts/run_allocator_preload_matrix.sh
```

## 3) Scenario bench（bench_allocators_compare.sh）

シナリオ別（json/mir/vm/mixed）を CSV で揃える。

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

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

## 4) 結果の記録先（SSOT）

- 比較手順: `docs/analysis/ALLOCATOR_COMPARISON_SSOT.md`
- 参照値の記録: `docs/analysis/PERFORMANCE_TARGETS_SCORECARD.md`（Allocator Comparison セクション）