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
```

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

### テンプレート

```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) - 環境変数リファレンス