hakmem/docs/archive/SETUP_GUIDE.md

# hakmem Setup Guide - インストール＆使用ガイド

**対象**: 新規利用者・評価者

---

## 🛠️ インストール

### **1. ビルド準備**
```bash
git clone <repository>
cd hakmem
make clean && make libhakmem.so
```

### **2. 動作確認**
```bash
make test          # 基本機能テスト
./test_bridge      # Bridge Classes確認 ✅
```

---

## 🚀 基本使用法

### **方法1: LD_PRELOAD推奨**
```bash
# モード選択 + 実行
HAKMEM_MODE=balanced LD_PRELOAD=./libhakmem.so your_program

# 既存コード変更不要
HAKMEM_MODE=balanced LD_PRELOAD=./libhakmem.so redis-server
HAKMEM_MODE=balanced LD_PRELOAD=./libhakmem.so nginx
```

### **方法2: コード埋め込み**
```c
#include "hakmem.h"

// 簡単API
void* ptr = hak_alloc_cs(1024);
hak_free_cs(ptr, 1024);
```

---

## ⚙️ モード選択ガイド

### **balanced (推奨)**
- **用途**: 一般アプリケーション
- **機能**: BigCache + TLS最適化 + FROZENモード
- **メモリ**: 中程度
- **速度**: 高速

### **minimal (ベンチマーク用)**
- **用途**: ベースライン測定
- **機能**: 全機能OFF
- **メモリ**: 最小
- **速度**: 比較基準

### **fast (本番用)**
- **用途**: 高性能サーバー
- **機能**: TLS最適化 + FROZEN
- **メモリ**: 小
- **速度**: 最高速

### **learning/research**
- **用途**: 開発・デバッグ
- **機能**: 全機能 + 詳細ログ
- **メモリ**: 大
- **速度**: 遅い（デバッグ用）

---

## 📊 性能測定

### **快速ベンチマーク**
```bash
# 基本測定
./bench_comprehensive_hakmem --scenario tiny

# mimalloc比較
./bench_comprehensive_system --scenario tiny

# 結果比較
HAKMEM_MODE=balanced ./bench_hakmem.sh && echo "vs mimalloc baseline"
```

### **Larsonスレッドテスト**
```bash
# 1スレッド
scripts/run_larson.sh -d 10 -t 1 -p burst

# 4スレッド（本番想定）
scripts/run_larson.sh -d 10 -t 4 -p burst
```

---

## 🔧 詳細設定

### **環境変数一覧**
```bash
export HAKMEM_MODE=balanced              # メイン設定
export HAKMEM_WRAP_TINY=1               # Tiny Pool有効化
export HAKMEM_TINY_MAG_CAP=1024         # Tiny Magazine容量
export HAKMEM_SITE_RULES=1              # Site Rules（非推奨）
export HAKMEM_PROF=1                    # プロファイラ
export HAKMEM_PROF_SAMPLE=12            # サンプリング率
```

### **ペリメータ調整**
```bash
# Tiny Pool最適化（16B勝利の秘訣）
export HAKMEM_TINY_MAG_CAP=2048         # Magazine拡大

# スレッド競合削減
export HAKMEM_WRAP_TINY=1               # 有効化推奨
```

---

## 🎯 アプリケーション別設定

### **Web Server (nginx)**
```bash
# 推奨設定
HAKMEM_MODE=balanced \
HAKMEM_WRAP_TINY=1 \
LD_PRELOAD=./libhakmem.so nginx
```

### **Database (Redis)**
```bash
# 高速性優先  
HAKMEM_MODE=fast \
LD_PRELOAD=./libhakmem.so redis-server
```

### **ベンチマーク**
```bash
# 公平比較
HAKMEM_MODE=minimal \
LD_PRELOAD=./libhakmem.so ./benchmark_app
```

---

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

### **動作確認**
```bash
# Bridge Classes動作確認
./test_bridge

# Tiny Pool確認
./test_tiny

# 全体テスト
make test
```

### **性能低下時**
```bash
# プロファイラ有効化
HAKMEM_MODE=research HAKMEM_PROF=1 \
LD_PRELOAD=./libhakmem.so your_program

# 詳細分析
./view_perf_analysis.sh
```

### **メモリ使用量**
```bash
# フットプリント測定
./test_memory_footprint

# エコモード
HAKMEM_MODE=minimal LD_PRELOAD=./libhakmem.so
```

---

## 📈 成功事例

### **16B小規模アロケーション**
```bash
HAKMEM_MODE=balanced \
LD_PRELOAD=./libhakmem.so micro_benchmark
# 結果: mimalloc +3%勝利 ✅
```

### **混合サイズワークロード**  
```bash
HAKMEM_MODE=balanced \
LD_PRELOAD=./libhakmem.so web_server
# 結果: 全体+7.5%勝利 🔥
```

---

## 🎓 次のステップ

1. **基本評価**: `HAKMEM_MODE=balanced` で既存アプリを実行
2. **ベンチマーク**: `./bench_comprehensive_*` で測定
3. **最適化**: モード切り替えで性能調整
4. **本番デプロイ**: `balanced` + `HAKMEM_WRAP_TINY=1`

---

**サポート**: README.mdで詳細な技術情報、ソースコード参照