hakmem/docs/archive/claude.md

# hakmem - Claude向けクイックリファレンス

## 📚 主要ドキュメント

### 基本
- [README.md](README.md) - プロジェクト全体の概要
- [docs/INDEX.md](docs/INDEX.md) - ドキュメント索引

### 仕様・設定
- [docs/specs/CURRENT_SPEC.md](docs/specs/CURRENT_SPEC.md) - 現在の実装仕様（SACS-3、学習、環境変数）
- [docs/specs/ENV_VARS.md](docs/specs/ENV_VARS.md) - **環境変数の一覧と意味（30以上のオプション）**

### ベンチマーク
- [docs/benchmarks/README.md](docs/benchmarks/README.md) - 計測の流れ、保存場所、命名規則
- [docs/benchmarks/2025-10-22_SWEEP_NOTES.md](docs/benchmarks/2025-10-22_SWEEP_NOTES.md) - 最新の計測要約

### 実装状況
- [docs/status/IMPLEMENTATION_STATUS_2025_10_22.md](docs/status/IMPLEMENTATION_STATUS_2025_10_22.md) - 実装状況
- [PHASE_6.15_SUMMARY.md](PHASE_6.15_SUMMARY.md) - Phase 6.15の要約（TLS最適化）

## 🚀 クイックスタート

### ビルド
```bash
# 通常ビルド
make shared

# デバッグビルド（タイミング計測ON）
make debug

# ベンチマーク用（profiler組み込み）
make bench
```

### 基本的な使い方

#### 1. プリセットモードで実行
```bash
# BALANCED モード（推奨）
HAKMEM_MODE=balanced LD_PRELOAD=./libhakmem.so ./your_app

# MINIMAL モード（ベースライン、最適化OFF）
HAKMEM_MODE=minimal LD_PRELOAD=./libhakmem.so ./your_app

# LEARNING モード（自動学習）
HAKMEM_MODE=learning LD_PRELOAD=./libhakmem.so ./your_app
```

#### 2. タイミング計測
```bash
# 全カテゴリの実行時間を計測（終了時にstderrへ出力）
HAKMEM_TIMING=1 LD_PRELOAD=./libhakmem.so ./your_app
```

#### 3. Profilerでホットパス分析
```bash
# サンプリングprofiler有効化（1/4096サンプリング）
HAKMEM_PROF=1 LD_PRELOAD=./libhakmem.so ./your_app

# サンプリング率変更（1/256に）
HAKMEM_PROF=1 HAKMEM_PROF_SAMPLE=8 LD_PRELOAD=./libhakmem.so ./your_app
```

#### 4. 学習機能（自動キャッシュチューニング）
```bash
# 1秒ごとにヒット率を見てキャッシュ容量を自動調整
HAKMEM_LEARN=1 LD_PRELOAD=./libhakmem.so ./your_app

# パラメータ調整
HAKMEM_LEARN=1 \
  HAKMEM_TARGET_HIT_MID=0.70 \
  HAKMEM_LEARN_WINDOW_MS=500 \
  LD_PRELOAD=./libhakmem.so ./your_app
```

## 🔍 トレーシング・デバッグ機能

### Debug Timing（詳細なタイミング計測）
- **有効化**: `HAKMEM_TIMING=1`
- **測定項目**: lock取得、リフィル、ドレイン、TLS操作など
- **出力**: プログラム終了時にstderrへサイクル単位で統計出力

### Sampling Profiler（低オーバーヘッド）
- **有効化**: `HAKMEM_PROF=1`
- **サンプリング率**: `HAKMEM_PROF_SAMPLE=N`（1/2^N、デフォルト12=1/4096）
- **カテゴリ**: tiny_alloc, ace_alloc, pool_refill, l25_refillなど

### Learning（自動最適化）
- **有効化**: `HAKMEM_LEARN=1`
- **動作**: バックグラウンドスレッドで1秒ごとにヒット率を計測してCAP調整
- **パラメータ**: 目標ヒット率、ステップ、予算制約など

## ⚙️ よく使う環境変数

### モード設定
- `HAKMEM_MODE=minimal|fast|balanced|learning|research`

### キャッシュ容量（手動設定）
- `HAKMEM_CAP_MID=10,20,40,80,160` - Mid Pool (2/4/8/16/32KB)
- `HAKMEM_CAP_LARGE=2,4,8,16,32` - Large Pool (64K/128K/256K/512K/1MB)

### 丸め許容（W_MAX）
- `HAKMEM_WMAX_MID=1.4` - Midでの丸め許容率
- `HAKMEM_WMAX_LARGE=1.4` - Largeでの丸め許容率

### 安全性
- `HAKMEM_SAFE_FREE=1` - free()時にmincore()チェック（重い）

### その他
- `HAKMEM_THP=auto|on|off` - Transparent Huge Pages
- `HAKMEM_SHARD_MIX=1` - シャード分散強化

詳細は [docs/specs/ENV_VARS.md](docs/specs/ENV_VARS.md) を参照。

## 🧪 ベンチマーク

### Larson（マルチスレッド負荷テスト）
```bash
# 基本実行（10秒、1/4スレッド）
scripts/run_larson.sh -d 10 -t 1,4

# burst プリセット（同時保持が多い、厳しめ）
scripts/run_larson.sh -d 10 -t 1,4 -p burst

# loop プリセット（局所性が高い、甘め）
scripts/run_larson.sh -d 10 -t 1,4 -p loop
```

### mimalloc-bench
```bash
cd mimalloc-bench
./bench.sh
```

## 📊 アーキテクチャ

### 3層構造
- **L0: Tiny Pool** (≤1KB) - TLS Magazine + Slab
- **L1: ACE層** (1KB～2MB)
  - Mid Pool (2～32KB) - TLSリング+LIFO
  - Large Pool (64KB～1MB) - bump-run方式
- **L2: BigCache/mmap** (≥2MB) - LRU + カーネルmmap

### 主要コンポーネント
- `hakmem.c` - メインアロケータ
- `hakmem_ace.c` - L1統合層（Mid/Large routing）
- `hakmem_pool.c` - Mid Pool（2～32KB）
- `hakmem_l25_pool.c` - Large Pool（64KB～1MB）
- `hakmem_tiny.c` - Tiny Pool（≤1KB）
- `hakmem_policy.c` - FrozenPolicy（RCUスナップショット）
- `hakmem_learner.c` - 自動学習（バックグラウンドCAP調整）
- `hakmem_debug.c` - Debug Timing
- `hakmem_prof.c` - Sampling Profiler

## 🎯 現在の課題（2025-10-24更新）

### パフォーマンスギャップ
- **hakmem vs mimalloc**: 1Tで-41%、4Tで-48%の差
- **現状**: 4.0M ops/sec (hakmem) vs 6.8M ops/sec (mimalloc)

### 特定された問題点（調査完了）

#### 1. LD_PRELOADラッパーコンテキストの罠
- **原因**: `hak_in_wrapper()`がTiny/Mid Poolをスキップ
- **影響**: 小サイズ割り当て（10-1000バイト）が全てlibc mallocにフォールバック
- **タイミング**: fallback_malloc = 300 cycles (24.3%)

#### 2. WRAP有効化の逆効果 ⚠️
`HAKMEM_WRAP_TINY=1 HAKMEM_WRAP_L2=1`を試した結果：
- **パフォーマンス**: 4.0M → 3.2M ops/sec (**-20%悪化**)
- **原因**:
  - `pool_get`: 63 → **365 cycles (5.8倍！)**
  - `pool_alloc_tls_page`: **10,915 cycles** (重すぎる)
  - `tiny_alloc`: 131回のみ（5002回allocの2.6%しか使われていない）

#### 3. 詳細な問題点
1. **pool_alloc_tls_pageが激重**: 10,915 cycles
2. **Tiny Poolがほぼ未使用**: larsonは10-110バイトなのに2.6%のみ
3. **Mid Poolへの偏り**: pool_get が7,290回（allocの1.5倍）

### 次の調査項目
- [ ] サイズ分布の確認（larsonの実際の割り当てサイズ）
- [ ] pool_alloc_tls_pageの最適化（なぜ重いか）
- [ ] Tiny Pool判定ロジックの見直し（なぜ使われないか）
- [ ] コード構造の見直し（ultrathink調査予定）

Phase 6.15以降、**マルチスレッド性能**と**mimalloc比較**に注力中：
- TLS最適化によりスケーラビリティ向上
- freeの処理最適化
- より詳細なタイミング計測

詳細は最新のPHASE_*.mdドキュメントを参照。