# Debug Logging Policy

## 統一方針

すべての診断ログは **`HAKMEM_BUILD_RELEASE`** フラグで統一的に制御する。

### Build Modes

- **Release Build** (`HAKMEM_BUILD_RELEASE=1`): 診断ログ完全無効（性能最優先）
  - `-DNDEBUG` が定義されると自動的に有効
  - 本番環境・ベンチマーク用

- **Debug Build** (`HAKMEM_BUILD_RELEASE=0`): 診断ログ有効（デバッグ用）
  - デフォルト（NDEBUG未定義）
  - 環境変数で細かく制御可能

### Implementation Pattern

#### ✅ 推奨パターン（Guard関数）

```c
static inline int diagnostic_enabled(void) {
#if HAKMEM_BUILD_RELEASE
    return 0;  // Always disabled in release
#else
    // Check env var in debug builds
    static int enabled = -1;
    if (__builtin_expect(enabled == -1, 0)) {
        const char* env = getenv("HAKMEM_DEBUG_FEATURE");
        enabled = (env && *env != '0') ? 1 : 0;
    }
    return enabled;
#endif
}

// Usage
if (__builtin_expect(diagnostic_enabled(), 0)) {
    fprintf(stderr, "[DEBUG] ...\n");
}
```

#### ❌ 避けるパターン

```c
// 悪い例：環境変数を毎回チェック（getenv() は遅い）
const char* env = getenv("HAKMEM_DEBUG");
if (env && *env != '0') {
    fprintf(stderr, "...\n");
}

// 悪い例：無条件ログ（release でも出力される）
fprintf(stderr, "[DEBUG] ...\n");
```

### Existing Guard Functions

| 関数 | 用途 | ファイル |
|------|------|---------|
| `trc_refill_guard_enabled()` | Refill path 診断 | `core/tiny_refill_opt.h` |
| `g_debug_remote_guard` | Remote queue 診断 | `core/superslab/superslab_inline.h` |
| `tiny_refill_failfast_level()` | Fail-fast 検証 | `core/hakmem_tiny_free.inc` |

### Priority for Conversion

1. **🔥 Hot Path (最優先)**: Refill, Alloc, Free の fast path ✅ 完了
2. **⚠️ Medium**: Remote drain, Magazine 層
3. **✅ Low**: Initialization, Slow path

### Status

- ✅ `trc_refill_guard_enabled()` - Release build で完全無効化
- ⏳ 残り 92 箇所 - 必要に応じて対処

### Makefile Integration

現状：`NDEBUG` が定義されていない → `HAKMEM_BUILD_RELEASE=0`

TODO: Release ビルドターゲットに `-DNDEBUG` を追加
```makefile
release: CFLAGS += -DNDEBUG -O3
```

### Environment Variables (Debug Build Only)

- `HAKMEM_TINY_REFILL_FAILFAST`: Refill path 検証 (0=off, 1=on, 2=verbose)
- `HAKMEM_TINY_REFILL_OPT_DEBUG`: Refill 最適化ログ
- `HAKMEM_DEBUG_REMOTE_GUARD`: Remote queue 検証

## Performance Impact

| 状態 | Throughput | 改善 |
|------|-----------|------|
| Before (診断あり) | 1,015,347 ops/s | - |
| After (guard追加) | 1,046,392 ops/s | **+3.1%** |
| Target (完全無効化) | TBD | 推定 +5-10% |