hakmem/docs/archive/PROFILES.md

HAKMEM Configuration Profiles

作成日: 2025-11-26 目的: ユースケース別の推奨設定プロファイル

---

⚠️ 重要：学習機能の現状 ⚠️

実測結果（2025-11-26）:

• ✅ Default Profile（学習OFF）: 動作確認済み（83.19 M ops/s @Random Mixed 256B）
• ❌ Balanced/Adaptive/Tight（学習ON）: 実装が壊れています - SEGFAULT発生

現在の問題:

• HAKMEM_ALLOC_LEARN=1 を有効化すると即座にクラッシュ
• HAKMEM_MEM_LEARN=1 を有効化すると即座にクラッシュ
• Larson ベンチマークは学習OFFでもクラッシュ（TLS SLL corruption）

推奨:

• 本番環境では学習機能を使用しないでください（現時点では Default Profile のみ使用可能）
• 学習機能の修正は別タスクで対応予定

このドキュメントのステータス:

• Default Profile の数値: ✅ 実測済み（一部）
• Balanced/Adaptive/Tight の数値: ❌ 未検証・仮説値 - 実測不可能（実装が壊れている）

---

🎯 プロファイル選択ガイド

プロファイル	用途	性能	RSS	学習	推奨環境
Default	ベンチマーク・開発	⭐⭐⭐⭐⭐	⭐⭐⭐	OFF	短時間実行、予測可能なワークロード
Balanced	本番環境（汎用）	⭐⭐⭐⭐	⭐⭐⭐⭐	ON	Web サーバー、API サーバー
Adaptive	動的ワークロード	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	ON++	負荷変動が大きい環境
Tight	メモリ制約環境	⭐⭐⭐	⭐⭐⭐⭐⭐	ON	コンテナ、組み込み

---

📋 プロファイル詳細

1. Default Profile（デフォルト - ベンチマーク最適化）

特徴: 最高速、学習なし、固定キャッシュサイズ

# 学習機能: すべて OFF
export HAKMEM_ALLOC_LEARN=0
export HAKMEM_MEM_LEARN=0

# キャッシュ: 固定サイズ（Phase 10 aggressive defaults）
# → core/hakmem_tiny_config.c に定義済み:
#   C0-C3: 512/384 (hot classes)
#   C4-C5: 256/384 (medium)
#   C6-C7: 192/96 (cold)

# デバッグ: OFF
export HAKMEM_DEBUG_LEVEL=0
export HAKMEM_STATS_ENABLE=0

いつ使う:

• ✅ ベンチマーク測定
• ✅ 開発・デバッグ（予測可能な動作）
• ✅ 短時間実行（< 1分）
• ❌ 本番環境（RSS 肥大化リスク）

性能:

• Random Mixed 256B: 83.19 M ops/s ✅ 実測（2025-11-26）
• Larson 1T/8T: ❌ クラッシュ（TLS SLL corruption、未修正）

---

2. Balanced Profile（推奨 - 本番環境汎用）

特徴: 適度な学習、RSS とパフォーマンスのバランス

# 学習機能: Allocation Learning のみ ON
export HAKMEM_ALLOC_LEARN=1
export HAKMEM_ALLOC_LEARN_WINDOW=10000      # 10K ops ごとに学習
export HAKMEM_ALLOC_LEARN_RATE=0.1          # 10% ずつ調整

# Memory Learning: OFF（安定性優先）
export HAKMEM_MEM_LEARN=0

# SuperSlab: 適度な再利用
export HAKMEM_SUPERSLAB_REUSE=1             # 空 SuperSlab 再利用
export HAKMEM_SUPERSLAB_PREWARM=0           # 事前確保なし（必要時のみ）

# デバッグ: OFF（本番）
export HAKMEM_DEBUG_LEVEL=0
export HAKMEM_STATS_ENABLE=0

いつ使う:

• ❌ 現在使用不可 - HAKMEM_ALLOC_LEARN=1 が SEGFAULT を引き起こす
• （修正後の想定）Web サーバー、API サーバー、データベース、本番環境

性能: ❌ 未検証 - 学習機能が壊れているため測定不可能（仮説値: 95-100M ops/s） RSS: ❌ 未検証 - 学習機能が壊れているため測定不可能（仮説値: -20~30%）

---

3. Adaptive Profile（最適化 - 動的ワークロード）

特徴: 全学習機能 ON、ワークロード変化に自動追従

# 学習機能: すべて ON（積極的学習）
export HAKMEM_ALLOC_LEARN=1
export HAKMEM_ALLOC_LEARN_WINDOW=5000       # 5K ops（短め、素早く適応）
export HAKMEM_ALLOC_LEARN_RATE=0.15         # 15%（積極的調整）

export HAKMEM_MEM_LEARN=1
export HAKMEM_MEM_LEARN_WINDOW=10000        # 10K ops
export HAKMEM_MEM_LEARN_THRESHOLD=0.8       # 80% 使用率で THP 適用

# Advanced 学習（オプション）
export HAKMEM_LEARN_ADVANCED=1              # 上級パラメータ有効化

# SuperSlab: 積極的再利用
export HAKMEM_SUPERSLAB_REUSE=1
export HAKMEM_SUPERSLAB_PREWARM=2           # 2個事前確保

# 統計: ON（学習効果モニタリング）※旧プロトタイプ。現行版では HAKMEM_STATS/HAKMEM_STATS_DUMP を使用。

いつ使う:

• ❌ 現在使用不可 - HAKMEM_ALLOC_LEARN=1 + HAKMEM_MEM_LEARN=1 が SEGFAULT を引き起こす
• （修正後の想定）バッチ処理、機械学習、負荷変動が大きい環境、長時間稼働

性能: ❌ 未検証 - 学習機能が壊れているため測定不可能（仮説値: 105-110M ops/s） RSS: ❌ 未検証 - 学習機能が壊れているため測定不可能（仮説値: -30~40%）

---

4. Tight Profile（省メモリ - メモリ制約環境）

特徴: 最小 RSS、学習で厳格に管理

# 学習機能: ON（メモリ削減優先）
export HAKMEM_ALLOC_LEARN=1
export HAKMEM_ALLOC_LEARN_WINDOW=20000      # 20K ops（保守的）
export HAKMEM_ALLOC_LEARN_RATE=0.05         # 5%（慎重に調整）

export HAKMEM_MEM_LEARN=1
export HAKMEM_MEM_LEARN_WINDOW=20000
export HAKMEM_MEM_LEARN_THRESHOLD=0.9       # 90% 使用率（厳格）

# SuperSlab: 積極的解放
export HAKMEM_SUPERSLAB_REUSE=0             # 即座に解放
export HAKMEM_SUPERSLAB_PREWARM=0

# TINY: Ultra Tight プリセット使用
# → core/hakmem_tiny_config.h の TINY_PRESET_ULTRA_TIGHT()
#   C0-C7: 32/32/32/32/32/32/32 (最小キャッシュ)

# デバッグ: OFF
export HAKMEM_DEBUG_LEVEL=0
export HAKMEM_STATS_ENABLE=0

いつ使う:

• ❌ 現在使用不可 - HAKMEM_ALLOC_LEARN=1 + HAKMEM_MEM_LEARN=1 が SEGFAULT を引き起こす
• （修正後の想定）コンテナ、組み込みシステム、メモリ < 512MB 環境

性能: ❌ 未検証 - 学習機能が壊れているため測定不可能（仮説値: 70-80M ops/s） RSS: ❌ 未検証 - 学習機能が壊れているため測定不可能（仮説値: -50~60%）

---

🔧 プロファイル適用方法

方法 1: シェル設定ファイル（推奨）

# ~/.hakmem_profile.sh を作成
cat > ~/.hakmem_profile.sh << 'EOF'
# HAKMEM Balanced Profile (production)
export HAKMEM_ALLOC_LEARN=1
export HAKMEM_ALLOC_LEARN_WINDOW=10000
export HAKMEM_ALLOC_LEARN_RATE=0.1
export HAKMEM_MEM_LEARN=0
export HAKMEM_SUPERSLAB_REUSE=1
export HAKMEM_SUPERSLAB_PREWARM=0
export HAKMEM_DEBUG_LEVEL=0
EOF

# 適用
source ~/.hakmem_profile.sh
./your_application

方法 2: systemd サービス（本番環境）

# /etc/systemd/system/myapp.service
[Service]
EnvironmentFile=/etc/hakmem/balanced.env
ExecStart=/usr/bin/myapp

# /etc/hakmem/balanced.env
HAKMEM_ALLOC_LEARN=1
HAKMEM_ALLOC_LEARN_WINDOW=10000
HAKMEM_ALLOC_LEARN_RATE=0.1
# ...

方法 3: Docker / Kubernetes

# docker-compose.yml
services:
  myapp:
    image: myapp:latest
    environment:
      - HAKMEM_ALLOC_LEARN=1
      - HAKMEM_ALLOC_LEARN_WINDOW=10000
      - HAKMEM_ALLOC_LEARN_RATE=0.1
      # ...

---

📊 プロファイル比較（ベンチマーク結果）

注: ✅ = 実測済み、❌ = 未検証（学習機能が壊れているため測定不可能）

Benchmark	Default	Balanced	Adaptive	Tight
random_mixed (256B)	✅ 83.19 M ops/s	❌ N/A (SEGFAULT)	❌ N/A (SEGFAULT)	❌ N/A (SEGFAULT)
larson (1T)	❌ CRASH (TLS corruption)	❌ N/A	❌ N/A	❌ N/A
mid_large (8KB)	(未測定)	❌ N/A	❌ N/A	❌ N/A
RSS (1GB workload)	(未測定)	❌ N/A	❌ N/A	❌ N/A

以前の仮説値（検証失敗）:

• Default: 107 M ops/s @random_mixed, 47.6 M ops/s @larson ← 実測: 83.19 M / CRASH
• Balanced/Adaptive/Tight: 全て測定不可能（学習機能クラッシュ）

---

🎓 プロファイルのカスタマイズ

ケース 1: Balanced ベースで RSS をさらに削減

# Balanced をベースに
source ~/.hakmem_profile.sh  # Balanced

# TLS キャッシュを縮小
export HAKMEM_TINY_TLS_CLASS_OVERRIDE="C0:256:16,C1:256:16,C2:256:16,C3:192:12"
# → C0-C3 のキャッシュを半分に（512→256）

ケース 2: Adaptive ベースで統計を無効化

# Adaptive をベースに
source ~/.hakmem_adaptive.sh

# 統計 OFF（オーバーヘッド削減）
export HAKMEM_STATS_ENABLE=0

---

❓ FAQ

Q: デフォルトで本番環境使える？ A: ❌ デフォルトは学習 OFF で RSS が肥大化しやすい。本番は Balanced 推奨。

Q: 学習機能のオーバーヘッドは？ A: < 1%（HAKMEM_ALLOC_LEARN=1 のみ）。Adaptive でも < 3%。

Q: プロファイル切り替えに再起動必要？ A: ✅ 必要（ENV は起動時のみ読込）。systemd reload で適用可能。

Q: 自分のワークロードに最適なプロファイルは？ A: まず Balanced で試して、RSS が問題なら Tight、性能が足りなければ Default。

---

更新履歴:

• 2025-11-26: 初版作成（Phase 2 完了記念）