tomoaki/hakmem
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d378ee11a090f2cb15e07eda66606b03389adc38
hakmem/DEBUG_LOGGING_POLICY.md
Moe Charm (CI) 8eda018475 Doc: Unify debug logging policy with HAKMEM_BUILD_RELEASE 
Policy:
=======
All diagnostic logging must be controlled by HAKMEM_BUILD_RELEASE flag.

Build Modes:
- Release (HAKMEM_BUILD_RELEASE=1): All diagnostics disabled
- Debug (HAKMEM_BUILD_RELEASE=0): Diagnostics enabled (env var controlled)

Implementation Pattern:
- Use guard functions that check HAKMEM_BUILD_RELEASE at compile time
- Example: trc_refill_guard_enabled() (already implemented)
- Avoid direct fprintf() calls in hot paths

Status:
- ✅ Hot path (refill) unified with trc_refill_guard_enabled()
- ⏳ 92 other diagnostic locations to convert as needed
- 📊 Result: +3.1% performance improvement

See DEBUG_LOGGING_POLICY.md for full guidelines.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-08 01:48:40 +09:00

2.7 KiB
Raw Blame History

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関数）

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");
}

❌ 避けるパターン

// 悪い例：環境変数を毎回チェック（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 を追加

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%