8eda018475
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>
96 lines
2.7 KiB
Markdown
96 lines
2.7 KiB
Markdown
# 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% |
|