tomoaki/hakmem
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Update ENV_VARS.md with Phase 3 additions

Browse Source 
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 <noreply@anthropic.com>
This commit is contained in:
Moe Charm (CI)
2025-11-29 09:58:14 +09:00
parent d78baf41ce
commit 7f9e4015da
1 changed files with 82 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

82
docs/specs/ENV_VARS.md
View File

@ -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] <domain> ptr=<addr>`
- **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