From 7f9e4015da3cd158f30352f3afc47055c58069cb Mon Sep 17 00:00:00 2001 From: "Moe Charm (CI)" Date: Sat, 29 Nov 2025 09:58:14 +0900 Subject: [PATCH] docs: Update ENV_VARS.md with Phase 3 additions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Added documentation for new environment variables and build flags: Benchmark Environment Variables: - HAKMEM_BENCH_FAST_FRONT: Enable ultra-fast header-based free path - HAKMEM_BENCH_WARMUP: Warmup cycles before timed run - HAKMEM_FREE_ROUTE_TRACE: Debug trace for free() routing - HAKMEM_EXTERNAL_GUARD_LOG: ExternalGuard debug logging - HAKMEM_EXTERNAL_GUARD_STATS: ExternalGuard statistics at exit Build Flags: - HAKMEM_TINY_SS_TRUST_MMAP_ZERO: mmap zero-trust optimization - Default: 0 (safe) - Performance: +5.93% on bench_tiny_hot (allocation-heavy) - Safety: Release-only, cache reuse always gets full memset - Location: core/hakmem_build_flags.h:170-180 - Implementation: core/box/ss_allocation_box.c:37-78 Deprecated: - HAKMEM_DISABLE_MINCORE_CHECK: Removed in Phase 3 (commit d78baf41c) Each entry includes: - Default value - Usage example - Effect description - Source code location - A/B testing guidance (where applicable) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- docs/specs/ENV_VARS.md | 82 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 82 insertions(+) diff --git a/docs/specs/ENV_VARS.md b/docs/specs/ENV_VARS.md index e0ec8fab..85acf5b4 100644 --- a/docs/specs/ENV_VARS.md +++ b/docs/specs/ENV_VARS.md @@ -414,3 +414,85 @@ Total new master control variables: 6 HAKMEM_STATS, HAKMEM_STATS_DUMP All existing individual ENVs continue to work (backwards compatible) + +--- + +Benchmark Environment Variables (2025-11-29) +============================================= + +## HAKMEM_BENCH_FAST_FRONT +Enable ultra-fast header-based free path for benchmarks. +- **Default**: 0 (OFF) +- **Usage**: `HAKMEM_BENCH_FAST_FRONT=1 ./bench_random_mixed_hakmem` +- **Effect**: Tries hak_tiny_free_fast_v2() before normal free path +- **Location**: core/box/hak_free_api.inc.h:98-114 +- **A/B Testing**: Compare throughput with/without this flag + +## HAKMEM_BENCH_WARMUP +Number of warmup cycles before timed benchmark run. +- **Default**: 0 (no warmup) +- **Usage**: `HAKMEM_BENCH_WARMUP=1000000 ./bench_random_mixed_hakmem` +- **Effect**: Runs N allocation cycles (not timed) before starting benchmark +- **Purpose**: Warm up TLS caches, SuperSlabs, and system allocator +- **Location**: bench_random_mixed.c:69-92 + +## HAKMEM_FREE_ROUTE_TRACE +Debug trace for free() routing decisions. +- **Default**: 0 (OFF) +- **Usage**: `HAKMEM_FREE_ROUTE_TRACE=1 ./bench_random_mixed_hakmem` +- **Effect**: Logs first 32 free() routing decisions (tiny/pool/mid/external) +- **Output**: `[FREE_ROUTE] ptr=` +- **Location**: core/box/hak_free_api.inc.h:17-40 +- **Use case**: Debug which Box handles each free() + +## HAKMEM_EXTERNAL_GUARD_LOG +Enable ExternalGuard debug logging. +- **Default**: 0 (OFF) +- **Usage**: `HAKMEM_EXTERNAL_GUARD_LOG=1 ./bench` +- **Effect**: Logs all ExternalGuard calls with ptr info, SuperSlab lookup, FrontGate classification +- **Location**: core/box/external_guard_box.h:40-48 +- **Use case**: Debug unknown pointers that reach ExternalGuard + +## HAKMEM_EXTERNAL_GUARD_STATS +Print ExternalGuard statistics at exit. +- **Default**: 0 (OFF) +- **Usage**: `HAKMEM_EXTERNAL_GUARD_STATS=1 ./bench` +- **Output**: Total calls, unknown ptrs, etc. +- **Location**: core/box/external_guard_box.h:140-162 + +--- + +Build Flags (Compile-time, set via Makefile) +============================================= + +## HAKMEM_TINY_SS_TRUST_MMAP_ZERO +Skip large memset() for fresh mmap SuperSlabs (trust OS zero pages). +- **Default**: 0 (defensive memset enabled) +- **Build**: `HAKMEM_TINY_SS_TRUST_MMAP_ZERO=1 make bench_random_mixed_hakmem` + - Or: `EXTRA_MAKEFLAGS="HAKMEM_TINY_SS_TRUST_MMAP_ZERO=1" ./build.sh release bench_random_mixed_hakmem` +- **Effect**: + - When =1 AND release build AND fresh mmap (not from cache): + - Skip memset for slabs/remote_heads/remote_counts/slab_listed arrays + - Still memset class_map to 255 (UNASSIGNED) + - Cache reuse (from_cache=1): Always full memset (defensive) +- **Performance**: +5.93% on bench_tiny_hot, neutral on bench_random_mixed +- **Safety**: Only activates in release builds; cache reuse always gets full memset +- **Location**: + - Flag definition: core/hakmem_build_flags.h:170-180 + - Implementation: core/box/ss_allocation_box.c:37-78 +- **A/B Testing**: Compare fresh SuperSlab allocation throughput +- **Recommendation**: Keep default=0 for safety; enable for production after testing + +## HAKMEM_DISABLE_MINCORE_CHECK (REMOVED in Phase 3) +**DEPRECATED**: Removed in commit d78baf41c (Phase 3: Remove mincore() syscall completely) +- Previously controlled mincore() syscall in free path +- Now always disabled (trust internal metadata) +- See: CHECKPOINT_PHASE2_COMPLETE.md, PHASE2_PERF_ANALYSIS.md + +--- + +Update History: +- 2025-11-29: Added benchmark env vars (BENCH_FAST_FRONT, BENCH_WARMUP, FREE_ROUTE_TRACE) +- 2025-11-29: Added HAKMEM_TINY_SS_TRUST_MMAP_ZERO build flag +- 2025-11-29: Marked DISABLE_MINCORE_CHECK as removed +