hakmem/docs/archive/MIGRATION_GUIDE.md

hakmem Migration Guide - 移行ガイド

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

---

🚨 重要: Phase 6.21 重大変更

廃止された機能

// ❌ もう使えない
- DYN1/DYN2 (動的サイズクラス)
- Call-siteプロファイリング  
- UCB1/ELO自動学習
- 複雑なACE学習ループ

新しくなったコア

// ✅ 今の仕様
- 7固定クラス (+Bridge Classes)
- SACS-3 (Size-Only Allocation Strategy)
- TLS Active Slab
- シンプルな3階層

---

🔄 移行マトリクス

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

---

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

変化がある領域

# 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: 現行バージョン確認

# 現在の設定を保存
env | grep HAKMEM > hakmem_old_config.txt

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

ステップ2: コード更新

# 古いドキュメント削除
rm PHASE_6.*_COMPLETION_REPORT.md
rm *_LEARN_*.md

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

ステップ3: 環境変数更新

# 旧設定 (これらを削除)
unset HAKMEM_DYN1
unset HAKMEM_DYN2  
unset HAKMEM_LEARN
unset HAKMEM_UCB1

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

ステップ4: 再ビルド

make clean
make libhakmem.so
make test          # 動作確認

---

🎯 ケース別移行例

ケース1: Webサーバー (高接続)

# 旧設定
HAKMEM_LEARN=1 HAKMEM_DYN1=6144 LD_PRELOAD=./libhakmem.so nginx

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

ケース2: ベンチマーク環境

# 旧設定
HAKMEM_MODE=research HAKMEM_PROF=1 LD_PRELOAD=./libhakmem.so benchmark

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

ケース3: 開発/テスト

# 旧設定  
HAKMEM_MODE=learning HAKMEM_LEARN=1 LD_PRELOAD=./libhakmem.so dev_app

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

---

⚠️ 既知の移行問題

問題1: 性能低下 (1Tアプリ)

// 原因: CAP削除によるmiss頻度増加
// 対策: TLS Ring拡大
export HAKMEM_TLS_RING_CAP=32  // 16→32

問題2: Bridge動作不安定

# 検証
./test_bridge

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

問題3: メモリ使用量増加

// 原因: 新Bridgeクラス追加
// 影響: +2MB (無視できるレベル)
// 対策: 特になし

---

🔧 移行チェックリスト

前もって確認

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

移行作業中

• 旧環境変数クリア
• 新モード選択
• 再ビルド＆テスト
• Bridge Classes動作確認

移行後

• パフォーマンス再測定
• エラーログ確認
• 安定性検証
• ユーザー通知

---

📊 移行ROI分析

移行コスト

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

移行メリット

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

判定: 移行推奨

---

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

チューニング項目

# 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

検証コマンド

# 基本動作
make test && ./test_bridge

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

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

---

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

移行失敗時の対応

# 1. ロールバック準備
git checkout previous_version_tag

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

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

サポート

# 詳細なログ取得
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 を参照してください。