hakmem/docs/archive/MIGRATION_GUIDE.md

# hakmem Migration Guide - 移行ガイド

**対象**: 現行ユーザー・バージョンアップ・移行検討者

---

## 🚨 重要: Phase 6.21 重大変更

### **廃止された機能**
```c
// ❌ もう使えない
- DYN1/DYN2 (動的サイズクラス)
- Call-siteプロファイリング  
- UCB1/ELO自動学習
- 複雑なACE学習ループ
```

### **新しくなったコア**
```c
// ✅ 今の仕様
- 7固定クラス (+Bridge Classes)
- SACS-3 (Size-Only Allocation Strategy)
- TLS Active Slab
- シンプルな3階層
```

---

## 🔄 移行マトリクス

| 変更項目 | 従来 | 新仕様 | 影響度 | 対応 |
|----------|------|--------|--------|------|
| **サイズクラス** | 動的DYN1 | 固定Bridge (40KB,52KB) | 高 | 環境変数変更 |
| **学習機能** | ON (学習) | OFF (固定) | 中 | 設定調整 |
| **プロファイラ** | Call-site | なし | 低 | 無視 |
| **API互換性** | 互換性あり | 互換性あり | なし | 変更不要 |

---

## 📊 パフォーマンス影響分析

### **変化がある領域**
```bash
# 1T (シングルスレッド)
従来: 4.3M ops/sec
新仕様: 3.9M ops/sec (-8.6%)  

# 4T (マルチスレッド)  
従来: 9.6M ops/sec
新仕様: 10.0M ops/sec (+4.2%)
```

### **変化がない領域**
| 領域 | 影響 | 理由 |
|------|------|------|
| 16B-64KB | なし | Tiny Poolは変更なし |
| TLS機能 | なし | TLS Active Slabは維持 |
| API | なし | 互換性維持 |

---

## 🛠️ 移行手順

### **ステップ1: 現行バージョン確認**
```bash
# 現在の設定を保存
env | grep HAKMEM > hakmem_old_config.txt

# 学習機能使用確認
if [[ -n "${HAKMEM_LEARN}" ]]; then
    echo "学習機能使用中 → 移行必要"
fi
```

### **ステップ2: コード更新**
```bash
# 古いドキュメント削除
rm PHASE_6.*_COMPLETION_REPORT.md
rm *_LEARN_*.md

# 新ファイル確認
ls CURRENT_ARCHITECTURE.md QUICK_REFERENCE.md
```

### **ステップ3: 環境変数更新**
```bash
# 旧設定 (これらを削除)
unset HAKMEM_DYN1
unset HAKMEM_DYN2  
unset HAKMEM_LEARN
unset HAKMEM_UCB1

# 新設定 (これに置換)
export HAKMEM_MODE=balanced
export HAKMEM_WRAP_TINY=1    # Tiny Pool有効化
```

### **ステップ4: 再ビルド**
```bash
make clean
make libhakmem.so
make test          # 動作確認
```

---

## 🎯 ケース別移行例

### **ケース1: Webサーバー (高接続)**
```bash
# 旧設定
HAKMEM_LEARN=1 HAKMEM_DYN1=6144 LD_PRELOAD=./libhakmem.so nginx

# 新設定  
HAKMEM_MODE=fast HAKMEM_WRAP_TINY=1 LD_PRELOAD=./libhakmem.so nginx
```

### **ケース2: ベンチマーク環境**
```bash
# 旧設定
HAKMEM_MODE=research HAKMEM_PROF=1 LD_PRELOAD=./libhakmem.so benchmark

# 新設定
HAKMEM_MODE=minimal LD_PRELOAD=./libhakmem.so benchmark
```

### **ケース3: 開発/テスト**
```bash
# 旧設定  
HAKMEM_MODE=learning HAKMEM_LEARN=1 LD_PRELOAD=./libhakmem.so dev_app

# 新設定
HAKMEM_MODE=balanced LD_PRELOAD=./libhakmem.so dev_app
```

---

## ⚠️ 既知の移行問題

### **問題1: 性能低下 (1Tアプリ)**
```c
// 原因: CAP削除によるmiss頻度増加
// 対策: TLS Ring拡大
export HAKMEM_TLS_RING_CAP=32  // 16→32
```

### **問題2: Bridge動作不安定**
```bash
# 検証
./test_bridge

# 動作しない場合
export HAKMEM_MODE=minimal  # 一時的回避
```

### **問題3: メモリ使用量増加**
```c
// 原因: 新Bridgeクラス追加
// 影響: +2MB (無視できるレベル)
// 対策: 特になし
```

---

## 🔧 移行チェックリスト

### **前もって確認**
- [ ] 現行HAKMEMバージョン特定
- [ ] 使用中の環境変数リストアップ  
- [ ] 学習機能使用有無確認
- [ ] パフォーマンスベースライン記録

### **移行作業中**
- [ ] 旧環境変数クリア
- [ ] 新モード選択
- [ ] 再ビルド＆テスト
- [ ] Bridge Classes動作確認

### **移行後**
- [ ] パフォーマンス再測定
- [ ] エラーログ確認  
- [ ] 安定性検証
- [ ] ユーザー通知

---

## 📊 移行ROI分析

### **移行コスト**
```c
工数: 2-4時間 (標準アプリ)
リスク: 中 (1Tのみ性能低下)
学習コスト: 低 (後方互換性あり)
```

### **移行メリット**
```c
- メモリ使用量: 69%削減 (78MB→24MB)
- コード量: 33%削減 (899行→600行)  
- 保守性: 大幅向上
- マルチスレッド: +4%改善
```

### **判定**: 移行推奨

---

## 🎯 移行後のパフォーマンス最適化

### **チューニング項目**
```bash
# TLS Ring (1T性能回復)
export HAKMEM_TLS_RING_CAP=32

# Tiny Magazine (小規模最適化)  
export HAKMEM_TINY_MAG_CAP=2048

# 環境別最適モード
本番: HAKMEM_MODE=fast
テスト: HAKMEM_MODE=minimal  
開発: HAKMEM_MODE=balanced
```

### **検証コマンド**
```bash
# 基本動作
make test && ./test_bridge

# パフォーマンス測定  
./bench_comprehensive_hakmem --scenario tiny

# マルチスレッド確認
./test_scaling 4
```

---

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

### **移行失敗時の対応**
```bash
# 1. ロールバック準備
git checkout previous_version_tag

# 2. 最小構成でテスト
HAKMEM_MODE=minimal LD_PRELOAD=./libhakmem.so test_app

# 3. ステップアップ
# minimal -> balanced -> fast
```

### **サポート**
```bash
# 詳細なログ取得
HAKMEM_MODE=research HAKMEM_PROF=1 LD_PRELOAD=./libhakmem.so app 2>hakmem.log

# 問題報告用情報収集
./collect_debug_info.sh
```

---

## 📝 まとめ

Phase 6.21への移行は**推奨**されます：

- **機能削除**: 複雑な学習機能 (不要)
- **性能改善**: 4T +4%、メモリ -69%
- **保守性**: コード量33%削減
- **リスク管理**: 1Tのみ-8% (チューニングで回復可能)

**移行判断基準**:
- マルチスレッド利用→ **即時移行** ✅
- シングルスレッドのみ→ **慎重評価** ⚠️
- 学習機能不要→ **移行推奨** ✅

---

*移行に関する技術的な質問は docs/CURRENT_ARCHITECTURE.md を参照してください。*