hakmem/docs/archive/SETUP_GUIDE.md

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

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

---

🛠️ インストール

1. ビルド準備

git clone <repository>
cd hakmem
make clean && make libhakmem.so

2. 動作確認

make test          # 基本機能テスト
./test_bridge      # Bridge Classes確認 ✅

---

🚀 基本使用法

方法1: LD_PRELOAD推奨

# モード選択 + 実行
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: コード埋め込み

#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

• 用途: 開発・デバッグ
• 機能: 全機能 + 詳細ログ
• メモリ: 大
• 速度: 遅い（デバッグ用）

---

📊 性能測定

快速ベンチマーク

# 基本測定
./bench_comprehensive_hakmem --scenario tiny

# mimalloc比較
./bench_comprehensive_system --scenario tiny

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

Larsonスレッドテスト

# 1スレッド
scripts/run_larson.sh -d 10 -t 1 -p burst

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

---

🔧 詳細設定

環境変数一覧

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            # サンプリング率

ペリメータ調整

# Tiny Pool最適化（16B勝利の秘訣）
export HAKMEM_TINY_MAG_CAP=2048         # Magazine拡大

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

---

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

Web Server (nginx)

# 推奨設定
HAKMEM_MODE=balanced \
HAKMEM_WRAP_TINY=1 \
LD_PRELOAD=./libhakmem.so nginx

Database (Redis)

# 高速性優先  
HAKMEM_MODE=fast \
LD_PRELOAD=./libhakmem.so redis-server

ベンチマーク

# 公平比較
HAKMEM_MODE=minimal \
LD_PRELOAD=./libhakmem.so ./benchmark_app

---

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

動作確認

# Bridge Classes動作確認
./test_bridge

# Tiny Pool確認
./test_tiny

# 全体テスト
make test

性能低下時

# プロファイラ有効化
HAKMEM_MODE=research HAKMEM_PROF=1 \
LD_PRELOAD=./libhakmem.so your_program

# 詳細分析
./view_perf_analysis.sh

メモリ使用量

# フットプリント測定
./test_memory_footprint

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

---

📈 成功事例

16B小規模アロケーション

HAKMEM_MODE=balanced \
LD_PRELOAD=./libhakmem.so micro_benchmark
# 結果: mimalloc +3%勝利 ✅

混合サイズワークロード

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で詳細な技術情報、ソースコード参照