hakmem/LARSON_GUIDE.md

# Larson Benchmark - 統合ガイド

## 🚀 クイックスタート

### 1. 基本的な使い方

```bash
# HAKMEM を実行（duration=2秒, threads=4）
./scripts/larson.sh hakmem 2 4

# 3者比較（HAKMEM vs mimalloc vs system）
./scripts/larson.sh battle 2 4

# Guard モード（デバッグ/安全性チェック）
./scripts/larson.sh guard 2 4
```

### 2. プロファイルを使った実行

```bash
# スループット最適化プロファイル
./scripts/larson.sh hakmem --profile tinyhot_tput 2 4

# カスタムプロファイルを作成
cp scripts/profiles/tinyhot_tput.env scripts/profiles/my_profile.env
# my_profile.env を編集
./scripts/larson.sh hakmem --profile my_profile 2 4
```

## 📋 コマンド一覧

### ビルドコマンド

```bash
./scripts/larson.sh build              # 全ターゲットをビルド
```

### 実行コマンド

```bash
./scripts/larson.sh hakmem <dur> <thr> # HAKMEM のみ実行
./scripts/larson.sh mi <dur> <thr>     # mimalloc のみ実行
./scripts/larson.sh sys <dur> <thr>    # system malloc のみ実行
./scripts/larson.sh battle <dur> <thr> # 3者比較 + 結果保存
```

### デバッグコマンド

```bash
./scripts/larson.sh guard <dur> <thr>  # Guard モード（全安全チェックON）
./scripts/larson.sh debug <dur> <thr>  # Debug モード（性能+リングダンプ）
./scripts/larson.sh asan <dur> <thr>   # AddressSanitizer
./scripts/larson.sh ubsan <dur> <thr>  # UndefinedBehaviorSanitizer
./scripts/larson.sh tsan <dur> <thr>   # ThreadSanitizer
```

## 🎯 プロファイル詳細

### tinyhot_tput.env（スループット最適化）

**用途:** ベンチマークで最高性能を出す

**設定:**
- Tiny Fast Path: ON
- Fast Cap 0/1: 64
- Refill Count Hot: 64
- デバッグ: すべてOFF

**実行例:**
```bash
./scripts/larson.sh hakmem --profile tinyhot_tput 2 4
```

### larson_guard.env（安全性/デバッグ）

**用途:** バグ再現、メモリ破壊の検出

**設定:**
- Trace Ring: ON
- Safe Free: ON (strict mode)
- Remote Guard: ON
- Fast Cap: 0（無効化）

**実行例:**
```bash
./scripts/larson.sh guard 2 4
```

### larson_debug.env（性能+デバッグ）

**用途:** 性能測定しつつリングダンプ可能

**設定:**
- Tiny Fast Path: ON
- Trace Ring: ON（SIGUSR2でダンプ可能）
- Safe Free: OFF（性能重視）
- Debug Counters: ON

**実行例:**
```bash
./scripts/larson.sh debug 2 4
```

## 🔧 環境変数の確認（本線=セグフォ無し）

実行前に環境変数が表示されます：

```
[larson.sh] ==========================================
[larson.sh] Environment Configuration:
[larson.sh] ==========================================
[larson.sh] Tiny Fast Path:        1
[larson.sh] SuperSlab:             1
[larson.sh] SS Adopt:              1
[larson.sh] Box Refactor:          1
[larson.sh] Fast Cap 0:            64
[larson.sh] Fast Cap 1:            64
[larson.sh] Refill Count Hot:      64
[larson.sh] ...
```

## 🧯 安全ガイド（必ず通すチェック）

- Guard モード（Fail‑Fast + リング）: `./scripts/larson.sh guard 2 4`
- ASan/UBSan/TSan: `./scripts/larson.sh asan 2 4` / `ubsan` / `tsan`
- 期待するログ: `remote_invalid`/`SENTINEL_TRAP` が出ないこと。出る場合は採用境界以外で drain/bind/owner を触っていないかを確認。

## 🏆 Battle モード（3者比較）

**自動で以下を実行:**
1. 全ターゲットをビルド
2. HAKMEM, mimalloc, system を同一条件で実行
3. 結果を `benchmarks/results/snapshot_YYYYmmdd_HHMMSS/` に保存
4. スループット比較を表示

**実行例:**
```bash
./scripts/larson.sh battle 2 4
```

**出力:**
```
Results saved to: benchmarks/results/snapshot_20251105_123456/
Summary:
hakmem.txt:Throughput =  4740839 operations per second
mimalloc.txt:Throughput =  4500000 operations per second
system.txt:Throughput =  13500000 operations per second
```

## 🛠 トラブル対応（ハング・ログ見えない）

- 既定のランスクリプトはタイムアウトとログ保存を有効化しました（2025‑11‑06以降）。
  - 実行結果は `scripts/bench_results/larson_<name>_<thr>T_<dur>s_<min>-<max>.{stdout,stderr,txt}` に保存されます。
  - `stderr` は捨てずに保存します（以前は `/dev/null` へ捨てていました）。
  - ベンチ本体が固まっても `timeout` で強制終了し、スクリプトがブロックしません。
- 途中停止の見分け方:
  - `txt` に「(no Throughput line)」と出た場合は `stdout`/`stderr` を確認してください。
  - スレッド数は `== <name> threads=<N> ==` とファイル名の `<N>T` で確認できます。
- 古いプロセスが残った場合の掃除:
  - `pkill -f larson_hakmem || true`
  - もしくは `ps -ef | grep larson_` で PID を確認して `kill -9 <PID>`

## 📊 カスタムプロファイルの作成

### テンプレート

```bash
# my_profile.env
export HAKMEM_TINY_FAST_PATH=1
export HAKMEM_USE_SUPERSLAB=1
export HAKMEM_TINY_SS_ADOPT=1
export HAKMEM_TINY_FAST_CAP_0=32
export HAKMEM_TINY_FAST_CAP_1=32
export HAKMEM_TINY_REFILL_COUNT_HOT=32
export HAKMEM_TINY_TRACE_RING=0
export HAKMEM_TINY_SAFE_FREE=0
export HAKMEM_DEBUG_COUNTERS=0
export HAKMEM_TINY_PHASE6_BOX_REFACTOR=1
```

### 使用

```bash
cp scripts/profiles/tinyhot_tput.env scripts/profiles/my_profile.env
vim scripts/profiles/my_profile.env  # 編集
./scripts/larson.sh hakmem --profile my_profile 2 4
```

## 🐛 トラブルシューティング

### ビルドエラー

```bash
# クリーンビルド
make clean
./scripts/larson.sh build
```

### mimalloc がビルドできない

```bash
# mimalloc をスキップして実行
./scripts/larson.sh hakmem 2 4
```

### 環境変数が反映されない

```bash
# プロファイルが正しく読み込まれているか確認
cat scripts/profiles/tinyhot_tput.env

# 環境を手動設定して実行
export HAKMEM_TINY_FAST_PATH=1
./scripts/larson.sh hakmem 2 4
```

## 📝 既存スクリプトとの関係

**新しい統合スクリプト（推奨）:**
- `scripts/larson.sh` - すべてをここから実行

**既存スクリプト（後方互換）:**
- `scripts/run_larson_claude.sh` - まだ使える（将来的に deprecated）
- `scripts/run_larson_defaults.sh` - larson.sh に移行推奨

## 🎯 典型的なワークフロー

### 性能測定

```bash
# 1. スループット測定
./scripts/larson.sh hakmem --profile tinyhot_tput 2 4

# 2. 3者比較
./scripts/larson.sh battle 2 4

# 3. 結果確認
ls -la benchmarks/results/snapshot_*/
```

### バグ調査

```bash
# 1. Guard モードで再現
./scripts/larson.sh guard 2 4

# 2. ASAN で詳細確認
./scripts/larson.sh asan 2 4

# 3. リングダンプで解析（debug モード + SIGUSR2）
./scripts/larson.sh debug 2 4 &
PID=$!
sleep 1
kill -SIGUSR2 $PID  # リングダンプ
```

### A/B テスト

```bash
# プロファイルA
./scripts/larson.sh hakmem --profile profile_a 2 4

# プロファイルB
./scripts/larson.sh hakmem --profile profile_b 2 4

# 比較
grep "Throughput" benchmarks/results/snapshot_*/*.txt
```

## 📚 関連ドキュメント

- [CLAUDE.md](CLAUDE.md) - プロジェクト概要
- [PHASE6_3_FIX_SUMMARY.md](PHASE6_3_FIX_SUMMARY.md) - Tiny Fast Path 実装
- [ENV_VARS.md](ENV_VARS.md) - 環境変数リファレンス