ENV Cleanup Phase 5: Additional DEBUG guards + doc cleanup
Code changes: - core/slab_handle.h: Add RELEASE guard for HAKMEM_TINY_FREELIST_MASK - core/tiny_superslab_free.inc.h: Add guards for HAKMEM_TINY_ROUTE_FREE, HAKMEM_TINY_FREELIST_MASK Documentation cleanup: - docs/specs/CONFIGURATION.md: Remove 21 doc-only ENV variables - docs/specs/ENV_VARS.md: Remove doc-only variables Testing: - Build: PASS (305KB binary, unchanged) - Sanity: PASS (17.22M ops/s average, 3 runs) - Larson: PASS (52.12M ops/s, 0 crashes) Impact: - 2 additional DEBUG ENV variables guarded (no overhead in RELEASE) - Documentation accuracy improved - Binary size maintained 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Moe Charm (CI)
@ -44,36 +44,6 @@ export HAKMEM_WRAP_TINY=0 HAKMEM_WRAP_POOL=0 HAKMEM_WRAP_MID=0 HAKMEM_WRAP_LARGE
|
||||
|
||||
---
|
||||
|
||||
## 🐛 Debug & Diagnostics
|
||||
|
||||
**Canonical Variables** (After P0.4 - Debug Consolidation):
|
||||
|
||||
| Variable | Values | Default | Description |
|
||||
|----------|--------|---------|-------------|
|
||||
| `HAKMEM_DEBUG_LEVEL` | 0-3 | 0 | Verbosity (0=none, 1=errors, 2=info, 3=verbose) |
|
||||
| `HAKMEM_DEBUG_TINY` | 0, 1 | 0 | Enable TINY allocator debug output |
|
||||
| `HAKMEM_TRACE_ALLOCATIONS` | 0, 1 | 0 | Trace every alloc/free (expensive!) |
|
||||
| `HAKMEM_INTEGRITY_CHECKS` | 0, 1 | 1 | Enable integrity validation (canary checks) |
|
||||
|
||||
**Examples**:
|
||||
```bash
|
||||
# Production (quiet, integrity only)
|
||||
export HAKMEM_DEBUG_LEVEL=0
|
||||
export HAKMEM_INTEGRITY_CHECKS=1
|
||||
|
||||
# Debug session (verbose + TINY debug + tracing)
|
||||
export HAKMEM_DEBUG_LEVEL=3
|
||||
export HAKMEM_DEBUG_TINY=1
|
||||
export HAKMEM_TRACE_ALLOCATIONS=1
|
||||
export HAKMEM_INTEGRITY_CHECKS=1
|
||||
|
||||
# Performance testing (all checks OFF)
|
||||
export HAKMEM_DEBUG_LEVEL=0
|
||||
export HAKMEM_INTEGRITY_CHECKS=0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ SuperSlab Management
|
||||
|
||||
**Canonical Variables** (After P0.1 - SuperSlab Unification):
|
||||
@ -114,49 +84,22 @@ Controls adaptive sizing for allocator caches (TLS, SFC, capacity tuning).
|
||||
|
||||
| Variable | Values | Default | Description |
|
||||
|----------|--------|---------|-------------|
|
||||
| `HAKMEM_ALLOC_LEARN` | 0, 1 | 0 | Enable allocation pattern learning |
|
||||
| `HAKMEM_ALLOC_LEARN_WINDOW` | 1-1000000 | 10000 | Learning window size (operations) |
|
||||
| `HAKMEM_ALLOC_LEARN_RATE` | 0.0-1.0 | 0.1 | Learning rate (lower = slower adaptation) |
|
||||
|
||||
### Memory Learning
|
||||
Controls THP (Transparent Huge Pages), RSS optimization, and max-size learning.
|
||||
|
||||
| Variable | Values | Default | Description |
|
||||
|----------|--------|---------|-------------|
|
||||
| `HAKMEM_MEM_LEARN` | 0, 1 | 0 | Enable memory pattern learning (THP/RSS/WMAX) |
|
||||
| `HAKMEM_MEM_LEARN_WINDOW` | 1-1000000 | 5000 | Learning window size (operations) |
|
||||
| `HAKMEM_MEM_LEARN_THRESHOLD` | 0.0-1.0 | 0.8 | Activation threshold (80% confidence) |
|
||||
|
||||
### Advanced Overrides
|
||||
**For troubleshooting only** - enables legacy advanced knobs that are auto-tuned by default.
|
||||
|
||||
| Variable | Values | Default | Description |
|
||||
|----------|--------|---------|-------------|
|
||||
| `HAKMEM_LEARN_ADVANCED` | 0, 1 | 0 | Enable advanced override knobs (see DEPRECATED.md) |
|
||||
|
||||
**Examples**:
|
||||
```bash
|
||||
# Production (learning disabled, use static tuning)
|
||||
export HAKMEM_ALLOC_LEARN=0
|
||||
export HAKMEM_MEM_LEARN=0
|
||||
|
||||
# Adaptive workload (enable both learners)
|
||||
export HAKMEM_ALLOC_LEARN=1
|
||||
export HAKMEM_ALLOC_LEARN_WINDOW=20000
|
||||
export HAKMEM_ALLOC_LEARN_RATE=0.05
|
||||
export HAKMEM_MEM_LEARN=1
|
||||
export HAKMEM_MEM_LEARN_WINDOW=10000
|
||||
export HAKMEM_MEM_LEARN_THRESHOLD=0.75
|
||||
|
||||
# Migration troubleshooting (enable advanced overrides)
|
||||
export HAKMEM_LEARN_ADVANCED=1
|
||||
export HAKMEM_LEARN_DECAY=0.95 # Override auto-tuned decay
|
||||
```
|
||||
|
||||
**Migration Note**: See [DEPRECATED.md](DEPRECATED.md) for mapping of 18 legacy variables → 6 canonical variables.
|
||||
|
||||
---
|
||||
|
||||
## 🎯 TINY Allocator (1-2048B)
|
||||
|
||||
### TLS Cache Configuration
|
||||
@ -237,18 +180,10 @@ export HAKMEM_POOL_TLS_ARENA_GROWTH_LEVELS=5 # 4MB→8MB→16MB→32MB
|
||||
|
||||
| Variable | Values | Default | Description |
|
||||
|----------|--------|---------|-------------|
|
||||
| `HAKMEM_STATS_ENABLE` | 0, 1 | 0 | Enable statistics collection |
|
||||
| `HAKMEM_STATS_VERBOSE` | 0, 1 | 0 | Verbose stats output |
|
||||
| `HAKMEM_STATS_INTERVAL_SEC` | 1-3600 | 10 | Stats reporting interval (seconds) |
|
||||
| `HAKMEM_PROFILE_SYSCALLS` | 0, 1 | 0 | Profile syscall counts (mmap/munmap/madvise) |
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
# Enable stats for performance analysis
|
||||
export HAKMEM_STATS_ENABLE=1
|
||||
export HAKMEM_STATS_VERBOSE=1
|
||||
export HAKMEM_STATS_INTERVAL_SEC=5
|
||||
export HAKMEM_PROFILE_SYSCALLS=1
|
||||
```
|
||||
|
||||
---
|
||||
@ -259,8 +194,6 @@ export HAKMEM_PROFILE_SYSCALLS=1
|
||||
|
||||
| Variable | Values | Default | Description |
|
||||
|----------|--------|---------|-------------|
|
||||
| `HAKMEM_EXPERIMENTAL_ADAPTIVE_DRAIN` | 0, 1 | 0 | Adaptive remote free drain threshold |
|
||||
| `HAKMEM_EXPERIMENTAL_CACHE_TUNING` | 0, 1 | 0 | Runtime cache capacity tuning |
|
||||
|
||||
---
|
||||
|
||||
@ -272,16 +205,12 @@ export HAKMEM_PROFILE_SYSCALLS=1
|
||||
export HAKMEM_SUPERSLAB_LAZY=1
|
||||
export HAKMEM_SUPERSLAB_LRU_CAP=256
|
||||
export HAKMEM_TINY_P0_ENABLE=1
|
||||
export HAKMEM_INTEGRITY_CHECKS=1
|
||||
```
|
||||
|
||||
### 2. Debug Session
|
||||
```bash
|
||||
# Verbose logging, tracing, integrity checks
|
||||
export HAKMEM_DEBUG_LEVEL=3
|
||||
export HAKMEM_DEBUG_TINY=1
|
||||
export HAKMEM_TRACE_ALLOCATIONS=1
|
||||
export HAKMEM_INTEGRITY_CHECKS=1
|
||||
export HAKMEM_TINY_P0_LOG=1
|
||||
```
|
||||
|
||||
@ -327,13 +256,11 @@ export HAKMEM_POOL_TLS_ARENA_MB_MAX=2
|
||||
./scripts/validate_config.sh
|
||||
|
||||
# Example output:
|
||||
# [DEPRECATED] HAKMEM_LEARN is deprecated, use HAKMEM_ALLOC_LEARN instead
|
||||
# Sunset date: 2026-05-26 (6 months from 2025-11-26)
|
||||
# See DEPRECATED.md for migration guide
|
||||
#
|
||||
# [WARN] HAKMEM_TINY_TLS_CAP=2048 is outside typical range (16-1024)
|
||||
#
|
||||
# [OK] HAKMEM_DEBUG_LEVEL=2
|
||||
# [OK] HAKMEM_SUPERSLAB_LAZY=1
|
||||
```
|
||||
|
||||
@ -355,8 +282,6 @@ export HAKMEM_POOL_TLS_ARENA_MB_MAX=2
|
||||
|
||||
### Q: What's the difference between ALLOC_LEARN and MEM_LEARN?
|
||||
**A**:
|
||||
- `HAKMEM_ALLOC_LEARN`: Tunes **allocator behavior** (cache sizes, refill batches) based on allocation patterns
|
||||
- `HAKMEM_MEM_LEARN`: Tunes **memory management** (THP usage, RSS optimization, max-size detection)
|
||||
|
||||
### Q: Should I enable learning in production?
|
||||
**A**: **Generally NO**. Learning adds overhead (~5-10%) and is best for:
|
||||
|
||||
@ -276,10 +276,3 @@ LD safety (for apps/LD_PRELOAD runs)
|
||||
- HAKMEM_TINY_BENCH_MODE=1
|
||||
- ベンチ専用の簡素化採用パスを有効化。per-class 単一点の公開スロットを使用し、superslab_refill のスキャンと多段リング走査を回避。
|
||||
- OOMガード（harvest/trim）は保持。A/B用途に限定してください。
|
||||
|
||||
Runner build knobs（scripts/run_larson_claude.sh）
|
||||
- HAKMEM_BUILD_3LAYER=1
|
||||
- `make larson_hakmem_3layer` を用いて 3-layer Tiny をビルドして実行（LTO=OFF/O1）。
|
||||
- HAKMEM_BUILD_ROUTE=1
|
||||
- `make larson_hakmem_route` を用いて 3-layer + Route 指紋（ビルド時ON）でビルドして実行。
|
||||
- 実行時は `HAKMEM_TINY_TRACE_RING=1 HAKMEM_ROUTE=1` を併用してリングにルートを出力。
|
||||
|
||||
Reference in New Issue
Block a user