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（デフォルト - ベンチマーク最適化）

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

```bash
# 学習機能: すべて 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 とパフォーマンスのバランス

```bash
# 学習機能: 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、ワークロード変化に自動追従

```bash
# 学習機能: すべて 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、学習で厳格に管理

```bash
# 学習機能: 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: シェル設定ファイル（推奨）

```bash
# ~/.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 サービス（本番環境）

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

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

### 方法 3: Docker / Kubernetes

```yaml
# 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 をさらに削減

```bash
# 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 ベースで統計を無効化

```bash
# 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 完了記念）