diff --git a/ENV_VARIABLE_SURVEY.md b/ENV_VARIABLE_SURVEY.md new file mode 100644 index 00000000..2881094e --- /dev/null +++ b/ENV_VARIABLE_SURVEY.md @@ -0,0 +1,822 @@ +# HAKMEM Environment Variable Survey +**Date:** 2025-11-28 +**Total Variables Found:** 228 +**Total getenv() Calls:** 320 + +--- + +## Executive Summary + +This document catalogs **all 228 environment variables** used in HAKMEM's codebase. The analysis reveals: + +- **Core functionality**: 15 essential variables +- **Performance tuning**: 45 tuning parameters +- **Learning/Adaptive**: 25 learning system variables +- **Debug/Diagnostic**: 65 debug/trace variables +- **Legacy/Deprecated**: 35+ candidates for removal +- **Recent additions (TLS SLL redesign)**: 20+ P2/P3 phase variables + +### Key Findings + +1. **Excessive complexity**: 228 environment variables is unmanageable +2. **Debugging bloat**: 65+ debug variables (28% of total) +3. **Overlap**: Multiple variables control similar features (e.g., 8+ trace variables) +4. **Legacy debt**: Many Phase 1-4 variables should be gated or removed +5. **Poor defaults**: Most debug variables default to OFF, requiring manual enable + +### Recommendations + +- **REMOVE**: 60+ debug/legacy variables (26% reduction) +- **CONSOLIDATE**: 40+ overlapping variables into 10 unified controls +- **KEEP**: 50-60 essential core/tuning variables +- **TARGET**: Reduce to ~80 total variables (65% reduction) + +--- + +## Category 1: Core/Toggle (15 variables) + +Essential on/off switches for major features. + +| Variable | Default | Purpose | Location | Recommendation | +|----------|---------|---------|----------|----------------| +| `HAKMEM_SFC_ENABLE` | 1 | Enable Super Front Cache | hakmem_tiny_sfc.c | **KEEP** - Critical perf feature | +| `HAKMEM_TINY_USE_SUPERSLAB` | 1 | Enable SuperSlab backend | box/hak_core_init.inc.h | **KEEP** - Core architecture | +| `HAKMEM_TINY_TLS_SLL` | 1 | Enable TLS SLL (Phase P2) | box/hak_core_init.inc.h | **KEEP** - Core P2 feature | +| `HAKMEM_SMALLMID_ENABLE` | 1 | Enable SmallMid pool | hakmem_smallmid.c | **KEEP** - Important pool | +| `HAKMEM_WRAP_TINY` | 0 | Wrap tiny allocs (bench) | hakmem.c | **KEEP** - Benchmark control | +| `HAKMEM_WRAP_L2` | 0 | Wrap L2 pool | box/pool_init_api.inc.h | **KEEP** | +| `HAKMEM_WRAP_L25` | 0 | Wrap L25 pool | hakmem_l25_pool.c | **KEEP** | +| `HAKMEM_FORCE_LIBC_ALLOC` | 0 | Force libc malloc | hakmem.c | **KEEP** - Fallback control | +| `HAKMEM_FORCE_LIBC_ALLOC_INIT` | 0 | Force libc during init | hakmem.c | **KEEP** - Init safety | +| `HAKMEM_ACE_ENABLED` | 0 | Enable ACE learning | box/ace_pool_connector.c | **KEEP** - Learning system | +| `HAKMEM_SAFE_FREE` | 0 | Enable safe free checks | box/hak_core_init.inc.h | **KEEP** - Safety feature | +| `HAKMEM_INVALID_FREE` | 0 | Detect invalid frees | box/hak_core_init.inc.h | **KEEP** - Bug detection | +| `HAKMEM_LD_SAFE` | 0 | LD_PRELOAD safety mode | box/hak_wrappers.inc.h | **KEEP** - LD safety | +| `HAKMEM_QUIET` | 0 | Suppress log output | hakmem_internal.h | **KEEP** - Logging control | +| `HAKMEM_BENCH_TINY_ONLY` | 0 | Benchmark tiny only | box/hak_core_init.inc.h | **KEEP** - Benchmark mode | + +**Status**: All 15 KEEP (essential core toggles) + +--- + +## Category 2: Learning/Adaptive Systems (25 variables) + +UCB1, ELO, INT, ACE, and capacity adjustment systems. + +### 2.1 ACE Controller (6 vars) +| Variable | Default | Purpose | Location | Recommendation | +|----------|---------|---------|----------|----------------| +| `HAKMEM_ACE_ENABLED` | 0 | Enable ACE controller | ace_pool_connector.c | **KEEP** - Core learning | +| `HAKMEM_ACE_PROFILE` | 0 | ACE profiling mode | ss_ace_box.c | **KEEP** | +| `HAKMEM_ACE_DEBUG` | 0 | ACE debug logs | ss_ace_box.c | **CONSOLIDATE** → `HAKMEM_DEBUG` | +| `HAKMEM_ACE_SAMPLE` | 1000 | ACE sample rate | hakmem_ace_stats.c | **KEEP** | +| `HAKMEM_ACE_OBSERVE` | 0 | ACE observe-only mode | hakmem_learner.c | **KEEP** | +| `HAKMEM_ACE_FAST_INTERVAL_MS` | 500 | ACE fast loop interval | hakmem_ace_controller.c | **KEEP** | + +### 2.2 EVO/Preset System (8 vars) +| Variable | Default | Purpose | Location | Recommendation | +|----------|---------|---------|----------|----------------| +| `HAKMEM_PRESET` | NULL | Preset config (prod/debug) | hakmem_evo.c | **KEEP** - User-friendly | +| `HAKMEM_EVO` | "auto" | Evolution policy | hakmem_evo.c | **KEEP** | +| `HAKMEM_EVO_SAMPLE` | NULL | EVO sample rate | box/hak_core_init.inc.h | **KEEP** | +| `HAKMEM_FREEZE_SEC` | 180 | Time before freeze | hakmem_evo.c | **KEEP** | +| `HAKMEM_FREEZE_EPSILON` | 0.01 | Convergence threshold | hakmem_evo.c | **KEEP** | +| `HAKMEM_RELEARN_DELTA` | 0.20 | Re-learn trigger (20%) | hakmem_evo.c | **KEEP** | +| `HAKMEM_CANARY_FRAC` | 0.05 | Canary sampling (5%) | hakmem_evo.c | **KEEP** | +| `HAKMEM_COOLDOWN_SEC` | 30 | State transition cooldown | hakmem_evo.c | **KEEP** | + +### 2.3 Adaptive Sizing (3 vars) +| Variable | Default | Purpose | Location | Recommendation | +|----------|---------|---------|----------|----------------| +| `HAKMEM_ADAPTIVE_SIZING` | 0 | Enable adaptive sizing | tiny_adaptive_sizing.c | **KEEP** | +| `HAKMEM_ADAPTIVE_LOG` | 0 | Log adaptive changes | tiny_adaptive_sizing.c | **CONSOLIDATE** → `HAKMEM_DEBUG` | +| `HAKMEM_LEARN_SAMPLE` | 100 | Learning sample rate | hakmem_learn_log.c | **KEEP** | + +### 2.4 ELO/Learner (8 vars) +| Variable | Default | Purpose | Location | Recommendation | +|----------|---------|---------|----------|----------------| +| `HAKMEM_DISABLE_ELO` | 0 | Disable ELO ranking | hakmem_config.c | **KEEP** | +| `HAKMEM_DYN1_AUTO` | 0 | Auto-tune DYN1 class | hakmem_learner.c | **KEEP** | +| `HAKMEM_DYN2_AUTO` | 0 | Auto-tune DYN2 class | hakmem_learner.c | **KEEP** | +| `HAKMEM_GAIN_W_MISS` | 0.1 | Weight miss gain | hakmem_learner.c | **KEEP** - Tuning param | +| `HAKMEM_LEARN` | NULL | Enable learning | hakmem_config.c | **DEPRECATE** - use ACE_ENABLED | +| `HAKMEM_MODE` | NULL | Legacy mode override | hakmem_config.c | **DEPRECATE** - use PRESET | +| `HAKMEM_PROF` | NULL | Legacy profiling | hakmem_config.c | **DEPRECATE** - use ACE_PROFILE | +| `HAKMEM_PROF_SAMPLE` | NULL | Legacy prof sample | hakmem_config.c | **DEPRECATE** | + +**Status**: 17 KEEP, 4 DEPRECATE, 4 CONSOLIDATE + +--- + +## Category 3: Performance Tuning (45 variables) + +Cache capacities, refill counts, thresholds, and pool parameters. + +### 3.1 SFC (Super Front Cache) - 10 vars +| Variable | Default | Purpose | Location | Recommendation | +|----------|---------|---------|----------|----------------| +| `HAKMEM_SFC_ENABLE` | 1 | Enable SFC | hakmem_tiny_sfc.c | **KEEP** | +| `HAKMEM_SFC_CAPACITY` | 128 | SFC default capacity | hakmem_tiny_sfc.c | **KEEP** | +| `HAKMEM_SFC_REFILL_COUNT` | 64 | SFC refill batch size | hakmem_tiny_sfc.c | **KEEP** | +| `HAKMEM_SFC_CAPACITY_CLASS{0-7}` | varies | Per-class SFC capacity | hakmem_tiny_sfc.c | **KEEP** - Fine tuning | +| `HAKMEM_SFC_REFILL_COUNT_CLASS{0-7}` | varies | Per-class refill count | hakmem_tiny_sfc.c | **KEEP** | +| `HAKMEM_SFC_CASCADE_PCT` | 75 | Cascade percentage | tiny_alloc_fast.inc.h | **KEEP** | +| `HAKMEM_TINY_SFC_CASCADE` | 1 | Enable cascade | tiny_alloc_fast.inc.h | **KEEP** | + +### 3.2 Capacity/Threshold Tuning - 20 vars +| Variable | Default | Purpose | Location | Recommendation | +|----------|---------|---------|----------|----------------| +| `HAKMEM_WMAX_MID` | 1.60 | Mid pool W_MAX | hakmem_policy.c | **KEEP** - Critical tuning | +| `HAKMEM_WMAX_LARGE` | 1.30 | Large pool W_MAX | hakmem_policy.c | **KEEP** | +| `HAKMEM_CAP_MID` | "64,64,64,32,16" | Mid pool capacities | hakmem_policy.c | **KEEP** | +| `HAKMEM_CAP_LARGE` | "8,8,4,2,1" | Large pool capacities | hakmem_policy.c | **KEEP** | +| `HAKMEM_CAP_MID_DYN1` | 0 | DYN1 class capacity | hakmem_policy.c | **KEEP** | +| `HAKMEM_CAP_MID_DYN2` | 0 | DYN2 class capacity | hakmem_policy.c | **KEEP** | +| `HAKMEM_MID_DYN1` | 0 | DYN1 class size (bytes) | hakmem_policy.c | **KEEP** | +| `HAKMEM_MID_DYN2` | 0 | DYN2 class size (bytes) | hakmem_policy.c | **KEEP** | +| `HAKMEM_TARGET_HIT_MID` | 0.95 | Mid hit rate target | hakmem_config.c | **KEEP** | +| `HAKMEM_TARGET_HIT_LARGE` | 0.90 | Large hit rate target | hakmem_config.c | **KEEP** | +| `HAKMEM_MID_TC` | 0 | Mid pool TCache enable | mid_tcache.h | **KEEP** | +| `HAKMEM_MID_TC_CAP` | 64 | Mid TCache capacity | mid_tcache.h | **KEEP** | +| `HAKMEM_TC_ENABLE` | 0 | Global TCache enable | box/pool_init_api.inc.h | **KEEP** | +| `HAKMEM_TC_UNBOUNDED` | 0 | Unbounded TCache | box/pool_init_api.inc.h | **KEEP** | +| `HAKMEM_TC_DRAIN_MAX` | 128 | TCache drain max | box/pool_init_api.inc.h | **KEEP** | +| `HAKMEM_TC_DRAIN_TRIGGER` | 256 | TCache drain trigger | box/pool_init_api.inc.h | **KEEP** | +| `HAKMEM_POOL_MIN_BUNDLE` | 8 | Min bundle size | box/pool_init_api.inc.h | **KEEP** | +| `HAKMEM_RING_RETURN_DIV` | 4 | Ring return divisor | box/pool_init_api.inc.h | **KEEP** | +| `HAKMEM_TLS_LO_MAX` | 16 | TLS low watermark | box/pool_init_api.inc.h | **KEEP** | +| `HAKMEM_TRYLOCK_PROBES` | 3 | Trylock probe count | box/pool_init_api.inc.h | **KEEP** | + +### 3.3 L25 Pool - 15 vars +| Variable | Default | Purpose | Location | Recommendation | +|----------|---------|---------|----------|----------------| +| `HAKMEM_L25_MIN_BUNDLE` | 8 | L25 min bundle | hakmem_l25_pool.c | **KEEP** | +| `HAKMEM_L25_DZ` | NULL | L25 danger zone | hakmem_l25_pool.c | **KEEP** | +| `HAKMEM_POOL_TLS_RING` | 0 | TLS ring buffer enable | hakmem_l25_pool.c | **KEEP** | +| `HAKMEM_L25_RUN_BLOCKS` | 16 | Run blocks count | hakmem_l25_pool.c | **KEEP** | +| `HAKMEM_L25_RUN_FACTOR` | 2 | Run factor multiplier | hakmem_l25_pool.c | **KEEP** | +| `HAKMEM_SHARD_MIX` | 0 | Shard mixing enable | hakmem_l25_pool.c | **KEEP** | +| `HAKMEM_L25_PREF` | 0 | L25 prefetch | hakmem_l25_pool.c | **KEEP** | +| `HAKMEM_L25_TC_SPILL` | 128 | L25 TC spill threshold | hakmem_l25_pool.c | **KEEP** | +| `HAKMEM_L25_TC_CAP` | 256 | L25 TC capacity | hakmem_l25_pool.c | **KEEP** | +| `HAKMEM_L25_BG_DRAIN` | 0 | Background drain enable | hakmem_l25_pool.c | **KEEP** | +| `HAKMEM_L25_BG_MS` | 100 | Background drain interval | hakmem_l25_pool.c | **KEEP** | +| `HAKMEM_L25_RING_TRIGGER` | 64 | Ring trigger count | hakmem_l25_pool.c | **KEEP** | +| `HAKMEM_L25_OWNER_INBOUND` | 0 | Owner inbound enable | hakmem_l25_pool.c | **KEEP** | +| `HAKMEM_L25_INBOUND_SLOTS` | 16 | Inbound slot count | hakmem_l25_pool.c | **KEEP** | +| `HAKMEM_L25_REMOTE_SAFE` | 0 | Remote safety checks | hakmem_l25_pool.c | **KEEP** | + +**Status**: All 45 KEEP (critical performance tuning) + +--- + +## Category 4: Debug/Diagnostic (65 variables) + +Trace, dump, logging, and debug features. **PRIMARY CONSOLIDATION TARGET**. + +### 4.1 Trace Variables (15 vars) - **CONSOLIDATE** +| Variable | Default | Purpose | Location | Recommendation | +|----------|---------|---------|----------|----------------| +| `HAKMEM_TINY_RF_TRACE` | 0 | Refill trace | tiny_refill.h | **CONSOLIDATE** → `HAKMEM_TRACE=refill` | +| `HAKMEM_FREE_ROUTE_TRACE` | 0 | Free route trace | box/hak_free_api.inc.h | **CONSOLIDATE** → `HAKMEM_TRACE=free` | +| `HAKMEM_FREE_WRAP_TRACE` | 0 | Free wrapper trace | box/hak_free_api.inc.h | **CONSOLIDATE** → `HAKMEM_TRACE=wrap` | +| `HAKMEM_SUPER_REG_REQTRACE` | 0 | SuperSlab req trace | box/hak_free_api.inc.h | **CONSOLIDATE** → `HAKMEM_TRACE=superslab` | +| `HAKMEM_TINY_MAILBOX_TRACE` | 0 | Mailbox trace | box/mailbox_box.c | **CONSOLIDATE** → `HAKMEM_TRACE=mailbox` | +| `HAKMEM_TINY_TRACE_RING` | 0 | Ring trace | hakmem_config.c | **CONSOLIDATE** → `HAKMEM_TRACE=ring` | +| `HAKMEM_PTR_TRACE` | NULL | Pointer trace (addr) | box/ptr_trace_box.h | **KEEP** - Useful debugging | +| `HAKMEM_PTR_TRACE_ALL` | 0 | Trace all pointers | box/ptr_trace_box.h | **KEEP** | +| `HAKMEM_PTR_TRACE_CLASS` | NULL | Trace by class | box/ptr_trace_box.h | **KEEP** | +| `HAKMEM_PTR_TRACE_VERBOSE` | 0 | Verbose ptr trace | box/ptr_trace_box.h | **CONSOLIDATE** | +| `HAKMEM_TINY_ROUTE_FREE` | 0 | Route free trace | hakmem_config.c | **CONSOLIDATE** | +| `HAKMEM_WATCH_ADDR` | NULL | Watch address | hakmem_config.c | **KEEP** - Debug tool | +| `HAKMEM_TINY_ALLOC_DEBUG` | 0 | Alloc debug | tiny_debug.h | **CONSOLIDATE** → `HAKMEM_DEBUG` | +| `HAKMEM_TINY_FAST_DEBUG` | 0 | Fast path debug | hakmem_tiny_fastcache.inc.h | **CONSOLIDATE** | +| `HAKMEM_ROUTE` | NULL | Route selection | tiny_route.h | **KEEP** - Route control | + +**Consolidation Plan**: Merge 10 trace variables into: +```bash +HAKMEM_TRACE=refill,free,wrap,superslab,mailbox,ring # Comma-separated +``` + +### 4.2 Debug Flags (20 vars) - **CONSOLIDATE** +| Variable | Default | Purpose | Location | Recommendation | +|----------|---------|---------|----------|----------------| +| `HAKMEM_SFC_DEBUG` | 0 | SFC debug logs | hakmem_tiny_sfc.c | **CONSOLIDATE** → `HAKMEM_DEBUG=sfc` | +| `HAKMEM_ACE_DEBUG` | 0 | ACE debug | ss_ace_box.c | **CONSOLIDATE** | +| `HAKMEM_SUPER_REG_DEBUG` | 0 | SuperReg debug | hakmem_super_registry.c | **CONSOLIDATE** | +| `HAKMEM_SUPER_LOOKUP_DEBUG` | 0 | Lookup debug | hakmem_super_registry.h | **CONSOLIDATE** | +| `HAKMEM_SS_LRU_DEBUG` | 0 | LRU debug | hakmem_super_registry.c | **CONSOLIDATE** | +| `HAKMEM_SS_PREWARM_DEBUG` | 0 | Prewarm debug | hakmem_super_registry.c | **CONSOLIDATE** | +| `HAKMEM_SS_ACQUIRE_DEBUG` | 0 | Acquire debug | hakmem_shared_pool.c | **CONSOLIDATE** | +| `HAKMEM_SS_FREE_DEBUG` | 0 | SS free debug | hakmem_shared_pool.c | **CONSOLIDATE** | +| `HAKMEM_TINY_SLL_DIAG` | 0 | SLL diagnostics | box/tls_sll_box.h | **CONSOLIDATE** | +| `HAKMEM_TINY_SLL_DRAIN_DEBUG` | 0 | SLL drain debug | box/tls_sll_drain_box.h | **CONSOLIDATE** | +| `HAKMEM_TINY_REFILL_OPT_DEBUG` | 0 | Refill opt debug | tiny_refill_opt.h | **CONSOLIDATE** | +| `HAKMEM_TINY_HEAP_V2_DEBUG` | 0 | HeapV2 debug | hakmem_config.c | **CONSOLIDATE** | +| `HAKMEM_EXTERNAL_GUARD_LOG` | 0 | External guard log | box/external_guard_box.h | **CONSOLIDATE** | +| `HAKMEM_DEBUG_SEGV` | 0 | SEGV handler debug | hakmem.c | **KEEP** - Safety | +| `HAKMEM_INVALID_FREE_LOG` | 0 | Invalid free logging | box/hak_core_init.inc.h | **KEEP** - Safety | +| `HAKMEM_TINY_ULTRA_DEBUG` | 0 | Ultra debug mode | box/hak_core_init.inc.h | **CONSOLIDATE** | +| `HAKMEM_TINY_PATH_DEBUG` | 0 | Path debug | hakmem_tiny_stats.c | **CONSOLIDATE** | +| `HAKMEM_TINY_FAST_DEBUG_MAX` | 100 | Fast debug limit | hakmem_tiny_fastcache.inc.h | **CONSOLIDATE** | +| `HAKMEM_ADAPTIVE_LOG` | 0 | Adaptive log | tiny_adaptive_sizing.c | **CONSOLIDATE** | +| `HAKMEM_LD_BLOCK_JEMALLOC` | 0 | Block jemalloc in LD | hakmem.c | **KEEP** - Compatibility | + +**Consolidation Plan**: Merge into `HAKMEM_DEBUG=sfc,ace,superslab,lru,...` + +### 4.3 Stats Dump (15 vars) - **CONSOLIDATE** +| Variable | Default | Purpose | Location | Recommendation | +|----------|---------|---------|----------|----------------| +| `HAKMEM_SFC_STATS_DUMP` | 0 | Dump SFC stats | hakmem_tiny_sfc.c | **CONSOLIDATE** → `HAKMEM_STATS=sfc` | +| `HAKMEM_TINY_FAST_STATS` | 0 | Fast path stats | tiny_fastcache.c | **CONSOLIDATE** | +| `HAKMEM_TINY_COUNTERS_DUMP` | 0 | Counter dump | hakmem_tiny_stats.c | **CONSOLIDATE** | +| `HAKMEM_TINY_REFILL_DUMP` | 0 | Refill dump | hakmem_tiny_stats.c | **CONSOLIDATE** | +| `HAKMEM_TINY_FRONT_DUMP` | 0 | Front dump | box/front_metrics_box.c | **CONSOLIDATE** | +| `HAKMEM_PTR_TRACE_DUMP` | 0 | Ptr trace dump | box/ptr_trace_box.h | **CONSOLIDATE** | +| `HAKMEM_ULTRA_SLIM_STATS` | 0 | Ultra slim stats | box/ultra_slim_alloc_box.h | **CONSOLIDATE** | +| `HAKMEM_EXTERNAL_GUARD_STATS` | 0 | Guard stats | box/external_guard_box.h | **CONSOLIDATE** | +| `HAKMEM_TINY_PAGEFAULT_DUMP` | 0 | Pagefault dump | box/pagefault_telemetry_box.c | **CONSOLIDATE** | +| `HAKMEM_TINY_INVARIANT_DUMP` | 0 | Invariant dump | box/ss_hot_cold_box.h | **CONSOLIDATE** | +| `HAKMEM_TINY_NEAREMPTY_DUMP` | 0 | Near-empty dump | hakmem_config.c | **CONSOLIDATE** | +| `HAKMEM_TINY_DUMP_ATEXIT_ONLY` | 0 | Dump at exit only | hakmem_tiny_stats.c | **CONSOLIDATE** | +| `HAKMEM_TINY_DUMP_RING_ATEXIT` | 0 | Ring dump at exit | hakmem_config.c | **CONSOLIDATE** | +| `HAKMEM_SHARED_POOL_LOCK_STATS` | 0 | Lock stats | hakmem_shared_pool.c | **CONSOLIDATE** | +| `HAKMEM_SHARED_POOL_STAGE_STATS` | 0 | Stage stats | hakmem_shared_pool.c | **CONSOLIDATE** | + +**Consolidation Plan**: Merge into `HAKMEM_STATS=sfc,fast,counters,refill,...` + +### 4.4 Sampling/Profiling (5 vars) +| Variable | Default | Purpose | Location | Recommendation | +|----------|---------|---------|----------|----------------| +| `HAKMEM_TINY_PROFILE` | 0 | Tiny profiling | tiny_alloc_fast.inc.h | **KEEP** - Profiling tool | +| `HAKMEM_HIST_SAMPLE` | 100 | Histogram sampling | hakmem_size_hist.c | **KEEP** | +| `HAKMEM_POOL_COUNT_SAMPLE` | 100 | Pool count sampling | box/pool_init_api.inc.h | **KEEP** | +| `HAKMEM_ROUTE_SAMPLE_LG` | 0 | Route sample log2 | tiny_route.h | **KEEP** | +| `HAKMEM_TIMING` | 0 | Timing measurements | hakmem_config.c | **KEEP** | + +### 4.5 Metrics/Telemetry (10 vars) +| Variable | Default | Purpose | Location | Recommendation | +|----------|---------|---------|----------|----------------| +| `HAKMEM_TINY_FRONT_METRICS` | 0 | Front metrics | box/front_metrics_box.c | **KEEP** | +| `HAKMEM_TINY_ACTIVE_TRACK` | 0 | Active slab tracking | tiny_alloc_fast.inc.h | **KEEP** | +| `HAKMEM_TINY_ALLOC_1024_METRIC` | 0 | 1024B alloc metric | tiny_alloc_fast.inc.h | **CONSOLIDATE** | +| `HAKMEM_TINY_HEAP_V2_STATS` | 0 | HeapV2 stats | tiny_alloc_fast.inc.h | **CONSOLIDATE** | +| `HAKMEM_TINY_PAGEFAULT_TELEMETRY` | 0 | Pagefault telemetry | box/pagefault_telemetry_box.c | **KEEP** | +| `HAKMEM_TINY_INVARIANT_CHECK` | 0 | Invariant checking | box/ss_hot_cold_box.h | **KEEP** - Correctness | +| `HAKMEM_TINY_SUKESUKE` | 0 | Transparency mode | hakmem_tiny_stats.c | **DEPRECATE** - Unclear | +| `HAKMEM_TINY_MAILBOX_TRACE_LIMIT` | 1000 | Mailbox trace limit | box/mailbox_box.c | **CONSOLIDATE** | +| `HAKMEM_TINY_MAILBOX_SLOWDISC` | 0 | Slow disc detect | box/mailbox_box.c | **KEEP** | +| `HAKMEM_TINY_MAILBOX_SLOWDISC_PERIOD` | 100 | Slow disc period | box/mailbox_box.c | **KEEP** | + +**Status**: 15 KEEP, 50 CONSOLIDATE into 3 unified variables + +--- + +## Category 5: Superslab/Backend (25 variables) + +Superslab allocation, prewarming, caching, and backend control. + +### 5.1 Superslab Core (10 vars) +| Variable | Default | Purpose | Location | Recommendation | +|----------|---------|---------|----------|----------------| +| `HAKMEM_TINY_USE_SUPERSLAB` | 1 | Use SuperSlab backend | box/hak_core_init.inc.h | **KEEP** - Core | +| `HAKMEM_TINY_SS_SHARED` | 0 | Shared SuperSlab pool | box/ss_unified_backend_box.c | **KEEP** | +| `HAKMEM_TINY_SS_CACHE` | 1 | Enable SS caching | box/ss_allocation_box.c | **KEEP** | +| `HAKMEM_TINY_SS_MAX_MB` | 256 | Max SS memory (MB) | box/ss_allocation_box.c | **KEEP** | +| `HAKMEM_TINY_SS_MIN_MB` | 16 | Min SS memory (MB) | box/ss_allocation_box.c | **KEEP** | +| `HAKMEM_TINY_SS_FORCE_LG` | 0 | Force large gran | box/ss_allocation_box.c | **KEEP** | +| `HAKMEM_TINY_SS_PRECHARGE` | 0 | Precharge SS | box/ss_allocation_box.c | **KEEP** | +| `HAKMEM_TINY_SS_POPULATE_ONCE` | 0 | Populate once | box/ss_allocation_box.c | **KEEP** | +| `HAKMEM_TINY_SS_FAULT_RATE` | 0.0 | Fault injection rate | box/ss_allocation_box.c | **KEEP** - Testing | +| `HAKMEM_TINY_SS_LEGACY_FALLBACK` | 0 | Legacy fallback | box/ss_unified_backend_box.c | **DEPRECATE** | + +### 5.2 Superslab Prewarm (5 vars) +| Variable | Default | Purpose | Location | Recommendation | +|----------|---------|---------|----------|----------------| +| `HAKMEM_TINY_PREWARM_ALL` | 0 | Prewarm all classes | box/ss_hot_prewarm_box.c | **KEEP** | +| `HAKMEM_PREWARM_SUPERSLABS` | 0 | Prewarm SuperSlabs | hakmem_super_registry.c | **KEEP** | +| `HAKMEM_TINY_PREWARM_CLASS{0-7}` | 0 | Per-class prewarm | box/ss_hot_prewarm_box.c | **KEEP** | +| `HAKMEM_SS_PREWARM_DEBUG` | 0 | Prewarm debug | hakmem_super_registry.c | **CONSOLIDATE** | +| `HAKMEM_TINY_SS_ADOPT` | 0 | SS adoption | hakmem_config.c | **KEEP** | + +### 5.3 Superslab Registry (5 vars) +| Variable | Default | Purpose | Location | Recommendation | +|----------|---------|---------|----------|----------------| +| `HAKMEM_SUPERSLAB_MAX_CACHED` | 64 | Max cached SS | hakmem_super_registry.c | **KEEP** | +| `HAKMEM_SUPERSLAB_MAX_MEMORY_MB` | 512 | Max SS memory | hakmem_super_registry.c | **KEEP** | +| `HAKMEM_SUPERSLAB_TTL_SEC` | 60 | SS TTL seconds | hakmem_super_registry.c | **KEEP** | +| `HAKMEM_SUPER_REG_DEBUG` | 0 | Registry debug | hakmem_super_registry.c | **CONSOLIDATE** | +| `HAKMEM_SUPER_LOOKUP_DEBUG` | 0 | Lookup debug | hakmem_super_registry.h | **CONSOLIDATE** | + +### 5.4 Backend Selection (5 vars) +| Variable | Default | Purpose | Location | Recommendation | +|----------|---------|---------|----------|----------------| +| `HAKMEM_TINY_SS_C23_UNIFIED` | 0 | C23 unified backend | box/ss_unified_backend_box.c | **KEEP** | +| `HAKMEM_TINY_SS_LEGACY_HINT` | 0 | Legacy hint | box/ss_legacy_backend_box.c | **DEPRECATE** | +| `HAKMEM_TINY_SS_PACK_C23` | 0 | C23 packing | hakmem_config.c | **KEEP** | +| `HAKMEM_SS_EMPTY_REUSE` | 1 | Reuse empty SS | hakmem_shared_pool.c | **KEEP** | +| `HAKMEM_SS_EMPTY_SCAN_LIMIT` | 8 | Empty scan limit | hakmem_shared_pool.c | **KEEP** | + +**Status**: 20 KEEP, 3 DEPRECATE, 2 CONSOLIDATE + +--- + +## Category 6: TLS SLL (P2/P3) - Recent Additions (20 variables) + +Phase P2/P3 TLS SLL redesign variables. + +### 6.1 TLS SLL Core (8 vars) +| Variable | Default | Purpose | Location | Recommendation | +|----------|---------|---------|----------|----------------| +| `HAKMEM_TINY_TLS_SLL` | 1 | Enable TLS SLL | box/hak_core_init.inc.h | **KEEP** - Core P2 | +| `HAKMEM_TINY_SLL_RING` | 256 | SLL ring size | box/tls_sll_box.h | **KEEP** | +| `HAKMEM_TINY_SLL_SAFEHEADER` | 1 | Safe header mode | box/tls_sll_box.h | **KEEP** | +| `HAKMEM_TINY_SLL_CANARY_FAST` | 0 | Fast canary check | box/tls_sll_box.h | **KEEP** | +| `HAKMEM_TINY_SLL_DIAG` | 0 | SLL diagnostics | box/tls_sll_box.h | **CONSOLIDATE** | +| `HAKMEM_TINY_SLL_DRAIN_ENABLE` | 1 | Enable drain | box/tls_sll_drain_box.h | **KEEP** | +| `HAKMEM_TINY_SLL_DRAIN_INTERVAL` | 1000 | Drain interval | box/tls_sll_drain_box.h | **KEEP** | +| `HAKMEM_TINY_SLL_DRAIN_DEBUG` | 0 | Drain debug | box/tls_sll_drain_box.h | **CONSOLIDATE** | + +### 6.2 Tension Drain (2 vars) +| Variable | Default | Purpose | Location | Recommendation | +|----------|---------|---------|----------|----------------| +| `HAKMEM_TINY_TENSION_DRAIN_ENABLE` | 1 | Tension drain | hakmem_shared_pool.c | **KEEP** | +| `HAKMEM_TINY_TENSION_DRAIN_THRESHOLD` | 512 | Tension threshold | hakmem_shared_pool.c | **KEEP** | + +### 6.3 Remote Free (5 vars) +| Variable | Default | Purpose | Location | Recommendation | +|----------|---------|---------|----------|----------------| +| `HAKMEM_TINY_DISABLE_REMOTE` | 0 | Disable remote free | tiny_remote.c | **KEEP** | +| `HAKMEM_TINY_REMOTE_SIDE` | 0 | Remote side (0/1) | tiny_remote.c | **KEEP** | +| `HAKMEM_TINY_REMOTE_DRAIN_THRESHOLD` | 256 | Remote drain thresh | tiny_remote.c | **KEEP** | +| `HAKMEM_TINY_ASSUME_1T` | 0 | Assume 1 thread | tiny_remote.c | **KEEP** - Opt | +| `HAKMEM_TINY_ALLOC_REMOTE_RELAX` | 0 | Relax remote rules | tiny_superslab_alloc.inc.h | **KEEP** | + +### 6.4 Refill Optimization (5 vars) +| Variable | Default | Purpose | Location | Recommendation | +|----------|---------|---------|----------|----------------| +| `HAKMEM_TINY_REG_SCAN_MAX` | 8 | Registry scan max | tiny_refill.h | **KEEP** | +| `HAKMEM_TINY_MID_REFILL_SIMPLE` | 0 | Simple mid refill | tiny_refill.h | **KEEP** | +| `HAKMEM_TINY_REFILL_FAILFAST` | 0 | Failfast refill | tiny_failfast.c | **KEEP** | +| `HAKMEM_TINY_REFILL_OPT_DEBUG` | 0 | Refill opt debug | tiny_refill_opt.h | **CONSOLIDATE** | +| `HAKMEM_TINY_RF_TRACE` | 0 | Refill trace | tiny_refill.h | **CONSOLIDATE** | + +**Status**: 15 KEEP, 5 CONSOLIDATE + +--- + +## Category 7: Free Path Optimization (15 variables) + +Free routing, fast paths, and optimization flags. + +### 7.1 Free Routing (5 vars) +| Variable | Default | Purpose | Location | Recommendation | +|----------|---------|---------|----------|----------------| +| `HAKMEM_TINY_FREE_FAST` | 1 | Fast free path | tiny_free_fast.inc.h | **KEEP** | +| `HAKMEM_TINY_FREE_TO_SS` | 0 | Free to SuperSlab | tiny_free_fast.inc.h | **KEEP** | +| `HAKMEM_FREE_POLICY` | NULL | Free policy override | hakmem_config.c | **KEEP** | +| `HAKMEM_BENCH_FAST_FRONT` | 0 | Bench fast front | box/hak_free_api.inc.h | **KEEP** - Bench | +| `HAKMEM_BENCH_FAST_MODE` | 0 | Bench fast mode | box/bench_fast_box.h | **KEEP** - Bench | + +### 7.2 Free Optimization Flags (10 vars) +| Variable | Default | Purpose | Location | Recommendation | +|----------|---------|---------|----------|----------------| +| `HAKMEM_TINY_NO_CLASS_MAP` | 0 | Disable class map | tiny_free_fast_v2.inc.h | **KEEP** - Opt flag | +| `HAKMEM_TINY_LARSON_FIX` | 1 | Larson bench fix | tiny_free_fast_v2.inc.h | **KEEP** - Bug fix | +| `HAKMEM_TINY_FREELIST_MASK` | 1 | Freelist masking | slab_handle.h | **KEEP** - Security | +| `HAKMEM_TINY_RESTORE_HEADER` | 0 | Restore header | tiny_nextptr.h | **KEEP** | +| `HAKMEM_TINY_WRITE_HEADER` | 0 | Write header | hakmem_config.c | **KEEP** | +| `HAKMEM_HDR_LIGHT` | 0 | Lightweight header | box/pool_init_api.inc.h | **KEEP** | +| `HAKMEM_POOL_TLS_FREE` | 0 | TLS free pool | box/pool_init_api.inc.h | **KEEP** | +| `HAKMEM_TINY_FLUSH_ON_EXIT` | 0 | Flush on exit | box/hak_core_init.inc.h | **KEEP** - Testing | +| `HAKMEM_TINY_SLAB_REUSE_GUARD` | 0 | Slab reuse guard | box/tls_slab_reuse_guard_box.h | **KEEP** - Safety | +| `HAKMEM_SITE_RULES` | NULL | Site-specific rules | box/hak_core_init.inc.h | **KEEP** | + +**Status**: All 15 KEEP (critical free path optimizations) + +--- + +## Category 8: Front/Heap Variants (12 variables) + +Front cache, Heap V2, and allocation path variants. + +### 8.1 Front Cache (6 vars) +| Variable | Default | Purpose | Location | Recommendation | +|----------|---------|---------|----------|----------------| +| `HAKMEM_TINY_FRONT_DIRECT` | 0 | Direct front alloc | hakmem_tiny_fastcache.inc.h | **KEEP** | +| `HAKMEM_TINY_FRONT_SLIM` | 0 | Slim front cache | tiny_alloc_fast.inc.h | **KEEP** | +| `HAKMEM_TINY_FRONT_V2` | 0 | Front V2 | hakmem_config.c | **KEEP** | +| `HAKMEM_TINY_FRONT_DISABLE_HEAPV2` | 0 | Disable HeapV2 | box/front_metrics_box.h | **KEEP** | +| `HAKMEM_TINY_FRONT_METRICS` | 0 | Front metrics | box/front_metrics_box.c | **CONSOLIDATE** | +| `HAKMEM_FRONT_GATE_UNIFIED` | 0 | Unified front gate | front/malloc_tiny_fast.h | **KEEP** | + +### 8.2 Heap V2 (4 vars) +| Variable | Default | Purpose | Location | Recommendation | +|----------|---------|---------|----------|----------------| +| `HAKMEM_TINY_HEAP_V2_STATS` | 0 | HeapV2 stats | tiny_alloc_fast.inc.h | **CONSOLIDATE** | +| `HAKMEM_TINY_HEAP_V2_DEBUG` | 0 | HeapV2 debug | hakmem_config.c | **CONSOLIDATE** | +| `HAKMEM_TINY_HEAP_V2_CLASS_MASK` | 0xFF | HeapV2 class mask | hakmem_config.c | **KEEP** | +| `HAKMEM_TINY_HEAP_V2_LEFTOVER_MODE` | 0 | Leftover mode | hakmem_config.c | **KEEP** | + +### 8.3 Special Alloc Modes (2 vars) +| Variable | Default | Purpose | Location | Recommendation | +|----------|---------|---------|----------|----------------| +| `HAKMEM_TINY_ULTRA_SLIM` | 0 | Ultra slim alloc | box/ultra_slim_alloc_box.h | **KEEP** | +| `HAKMEM_TINY_SMALL_MAG` | 0 | Small magazine | hakmem_config.c | **KEEP** | + +**Status**: 10 KEEP, 2 CONSOLIDATE + +--- + +## Category 9: Page Arena/THP (10 variables) + +Page arena, THP (Transparent Huge Pages), and memory management. + +### 9.1 Page Arena (5 vars) +| Variable | Default | Purpose | Location | Recommendation | +|----------|---------|---------|----------|----------------| +| `HAKMEM_PAGE_ARENA_ENABLE` | 1 | Enable page arena | page_arena.h | **KEEP** | +| `HAKMEM_PAGE_ARENA_HOT_SIZE` | 64 | Hot arena size (MB) | page_arena.h | **KEEP** | +| `HAKMEM_PAGE_ARENA_WARM_64K` | 16 | Warm 64K pool (MB) | page_arena.h | **KEEP** | +| `HAKMEM_PAGE_ARENA_WARM_128K` | 8 | Warm 128K pool (MB) | page_arena.h | **KEEP** | +| `HAKMEM_PAGE_ARENA_WARM_2M` | 32 | Warm 2M pool (MB) | page_arena.h | **KEEP** | + +### 9.2 THP (5 vars) +| Variable | Default | Purpose | Location | Recommendation | +|----------|---------|---------|----------|----------------| +| `HAKMEM_THP` | "auto" | THP mode | hakmem_config.c | **KEEP** | +| `HAKMEM_THP_LEARN` | 0 | THP learning | hakmem_config.c | **KEEP** | +| `HAKMEM_THP_ADOPT_PCT` | 0.75 | THP adopt % | hakmem_config.c | **KEEP** | +| `HAKMEM_THP_CANDIDATES` | 16 | THP candidates | hakmem_config.c | **KEEP** | +| `HAKMEM_POOL_TLS_ARENA_*` | varies | TLS arena config | hakmem_config.c | **KEEP** (3 vars) | + +**Status**: All 10 KEEP (important memory management) + +--- + +## Category 10: External/Batch/Misc (18 variables) + +External guard, batch processing, MF2, and miscellaneous. + +### 10.1 External Guard (3 vars) +| Variable | Default | Purpose | Location | Recommendation | +|----------|---------|---------|----------|----------------| +| `HAKMEM_EXTERNAL_GUARD_MINCORE` | 0 | Mincore validation | box/external_guard_box.h | **KEEP** - Safety | +| `HAKMEM_EXTERNAL_GUARD_LOG` | 0 | Guard logging | box/external_guard_box.h | **CONSOLIDATE** | +| `HAKMEM_EXTERNAL_GUARD_STATS` | 0 | Guard stats | box/external_guard_box.h | **CONSOLIDATE** | + +### 10.2 Batch/BigCache (3 vars) +| Variable | Default | Purpose | Location | Recommendation | +|----------|---------|---------|----------|----------------| +| `HAKMEM_BATCH_BG` | 0 | Background batch | hakmem_batch.c | **KEEP** | +| `HAKMEM_DISABLE_BATCH` | 0 | Disable batch | hakmem_config.c | **KEEP** | +| `HAKMEM_BIGCACHE_L25` | 0 | BigCache L25 | box/hak_free_api.inc.h | **KEEP** | +| `HAKMEM_DISABLE_BIGCACHE` | 0 | Disable BigCache | hakmem_config.c | **KEEP** | + +### 10.3 MF2 (Multi-Free Queue) - 4 vars +| Variable | Default | Purpose | Location | Recommendation | +|----------|---------|---------|----------|----------------| +| `HAKMEM_MF2_ENABLE` | 0 | Enable MF2 | box/pool_init_api.inc.h | **KEEP** | +| `HAKMEM_MF2_MAX_QUEUES` | 8 | Max queues | box/pool_init_api.inc.h | **KEEP** | +| `HAKMEM_MF2_LEASE_MS` | 100 | Lease time (ms) | box/pool_init_api.inc.h | **KEEP** | +| `HAKMEM_MF2_IDLE_THRESHOLD_US` | 1000 | Idle threshold (μs) | box/pool_init_api.inc.h | **KEEP** | + +### 10.4 Miscellaneous (8 vars) +| Variable | Default | Purpose | Location | Recommendation | +|----------|---------|---------|----------|----------------| +| `HAKMEM_VERBOSE` | 0 | Verbose logging | hakmem_config.c | **KEEP** | +| `HAKMEM_LOG_FILE` | NULL | Log file path | hakmem_config.c | **KEEP** | +| `HAKMEM_ALLOW_MALLOC_FALLBACK` | 1 | Allow malloc fallback | hakmem_internal.h | **KEEP** | +| `HAKMEM_TINY_MAX_CLASS` | 7 | Max tiny class | hakmem_config.c | **KEEP** | +| `HAKMEM_TINY_NEAREMPTY_PCT` | 0.1 | Near-empty % | hakmem_config.c | **KEEP** | +| `HAKMEM_TINY_UNIFIED_CACHE` | 0 | Unified cache | hakmem_config.c | **KEEP** | +| `HAKMEM_TINY_UNIFIED_SAMPLE` | 100 | Unified sampling | hakmem_config.c | **KEEP** | +| `LD_PRELOAD` | NULL | LD_PRELOAD detect | hakmem.c | **KEEP** - System var | + +**Status**: 16 KEEP, 2 CONSOLIDATE + +--- + +## Summary Statistics + +### Total Count by Category + +| Category | Total | KEEP | CONSOLIDATE | DEPRECATE | +|----------|-------|------|-------------|-----------| +| 1. Core/Toggle | 15 | 15 | 0 | 0 | +| 2. Learning/Adaptive | 25 | 17 | 4 | 4 | +| 3. Performance Tuning | 45 | 45 | 0 | 0 | +| 4. Debug/Diagnostic | 65 | 15 | 50 | 0 | +| 5. Superslab/Backend | 25 | 20 | 2 | 3 | +| 6. TLS SLL (P2/P3) | 20 | 15 | 5 | 0 | +| 7. Free Path Optimization | 15 | 15 | 0 | 0 | +| 8. Front/Heap Variants | 12 | 10 | 2 | 0 | +| 9. Page Arena/THP | 10 | 10 | 0 | 0 | +| 10. External/Batch/Misc | 18 | 16 | 2 | 0 | +| **TOTAL** | **228** | **163** | **65** | **7** | + +### Consolidation Plan + +**Before**: 228 variables +**After**: ~80 variables (65% reduction) + +#### Unified Variables (3 new) + +1. **HAKMEM_TRACE** (replaces 15 trace variables) + ```bash + HAKMEM_TRACE=refill,free,wrap,superslab,mailbox,ring,ptr,route + ``` + +2. **HAKMEM_DEBUG** (replaces 35 debug variables) + ```bash + HAKMEM_DEBUG=sfc,ace,superslab,lru,prewarm,acquire,free,sll,refill,heap,guard + ``` + +3. **HAKMEM_STATS** (replaces 15 dump variables) + ```bash + HAKMEM_STATS=sfc,fast,counters,refill,front,trace,slim,guard,fault,invariant + ``` + +--- + +## Detailed Recommendations + +### Immediate Actions (Phase 1) + +#### 1. Remove Legacy Variables (7 vars) +```bash +# Deprecated learning variables (replaced by ACE) +HAKMEM_LEARN # Use HAKMEM_ACE_ENABLED +HAKMEM_MODE # Use HAKMEM_PRESET +HAKMEM_PROF # Use HAKMEM_ACE_PROFILE +HAKMEM_PROF_SAMPLE # Use HAKMEM_ACE_SAMPLE + +# Deprecated backend variables +HAKMEM_TINY_SS_LEGACY_FALLBACK # Legacy backend removed +HAKMEM_TINY_SS_LEGACY_HINT # Legacy hints unused + +# Unclear/unused +HAKMEM_TINY_SUKESUKE # No clear purpose, remove +``` + +#### 2. Consolidate Debug Variables (50 vars → 1 var) +Create unified `HAKMEM_DEBUG` with comma-separated values: + +**Example**: +```c +// Before (multiple getenv calls) +const char* sfc_dbg = getenv("HAKMEM_SFC_DEBUG"); +const char* ace_dbg = getenv("HAKMEM_ACE_DEBUG"); +const char* ss_dbg = getenv("HAKMEM_SUPER_REG_DEBUG"); + +// After (single getenv, parse once at init) +static int g_debug_flags = 0; +#define DEBUG_SFC (1 << 0) +#define DEBUG_ACE (1 << 1) +#define DEBUG_SUPERSLAB (1 << 2) +// ... etc + +void init_debug_flags(void) { + const char* dbg = getenv("HAKMEM_DEBUG"); + if (!dbg) return; + if (strstr(dbg, "sfc")) g_debug_flags |= DEBUG_SFC; + if (strstr(dbg, "ace")) g_debug_flags |= DEBUG_ACE; + // ... +} + +// Usage +if (g_debug_flags & DEBUG_SFC) { + fprintf(stderr, "[SFC] ...\n"); +} +``` + +**Benefits**: +- Single `getenv()` call at init (vs 50+ calls) +- Bitfield checks faster than string compares +- User-friendly: `HAKMEM_DEBUG=sfc,ace,superslab` + +#### 3. Consolidate Stats Variables (15 vars → 1 var) +Same approach for `HAKMEM_STATS`: + +```bash +# Before +HAKMEM_SFC_STATS_DUMP=1 +HAKMEM_TINY_FAST_STATS=1 +HAKMEM_TINY_COUNTERS_DUMP=1 + +# After +HAKMEM_STATS=sfc,fast,counters +``` + +### Medium-term Actions (Phase 2) + +#### 4. Add ENV Variable Registry +Create `/mnt/workdisk/public_share/hakmem/core/hakmem_env_registry.c`: + +```c +typedef struct { + const char* name; + const char* category; + const char* default_val; + const char* description; + int deprecated; +} EnvVarInfo; + +static const EnvVarInfo g_env_registry[] = { + {"HAKMEM_SFC_ENABLE", "core", "1", "Enable Super Front Cache", 0}, + {"HAKMEM_SFC_CAPACITY", "tuning", "128", "SFC capacity per class", 0}, + // ... all 228 variables + {NULL, NULL, NULL, NULL, 0} +}; + +// Print all ENV variables +void hakmem_env_print_help(void); + +// Validate unknown ENV variables +void hakmem_env_validate(void); +``` + +**Benefits**: +- Self-documenting code +- Detect typos (e.g., `HAKMEM_SFC_EANBLE`) +- Generate docs automatically + +#### 5. Add ENV Variable Validation +Warn on unknown variables: + +```c +void hakmem_env_validate(void) { + extern char **environ; + for (char **env = environ; *env; ++env) { + if (strncmp(*env, "HAKMEM_", 7) != 0) continue; + + char *eq = strchr(*env, '='); + if (!eq) continue; + + size_t name_len = eq - *env; + char name[256]; + snprintf(name, sizeof(name), "%.*s", (int)name_len, *env); + + // Check if in registry + int found = 0; + for (const EnvVarInfo *info = g_env_registry; info->name; ++info) { + if (strcmp(name, info->name) == 0) { + found = 1; + if (info->deprecated) { + fprintf(stderr, "[WARN] ENV variable '%s' is deprecated\n", name); + } + break; + } + } + + if (!found) { + fprintf(stderr, "[WARN] Unknown ENV variable: %s (typo?)\n", name); + } + } +} +``` + +### Long-term Actions (Phase 3) + +#### 6. Create Configuration File Support +Move from ENV variables to config file: + +```toml +# /etc/hakmem.toml or ~/.hakmem.toml + +[core] +sfc_enable = true +tiny_use_superslab = true +quiet = false + +[tuning] +sfc_capacity = 128 +sfc_refill_count = 64 +wmax_mid = 1.60 +wmax_large = 1.30 + +[debug] +trace = ["refill", "free"] +stats = ["sfc", "counters"] +log_file = "/tmp/hakmem.log" + +[learning] +ace_enabled = false +preset = "production" +``` + +**Benefits**: +- Type-safe parsing (int, float, bool) +- Comments/documentation inline +- Version control friendly +- Easier for users than 228 ENV variables + +--- + +## Priority Matrix + +### Critical Issues (Fix Immediately) + +1. **Performance**: 50+ `getenv()` calls in hot paths + - **Impact**: Measurable overhead in malloc/free + - **Fix**: Cache at init, use bitfields + +2. **Usability**: 228 variables = impossible to remember + - **Impact**: Poor developer experience + - **Fix**: Consolidate to ~80, add help command + +3. **Maintainability**: Scattered `getenv()` calls + - **Impact**: Hard to track what's used + - **Fix**: Central registry + +### Quick Wins (Low effort, high impact) + +1. **Remove 7 deprecated variables** (10 minutes) +2. **Add ENV validation** (1 hour) +3. **Create HAKMEM_DEBUG consolidation** (4 hours) +4. **Document all variables in registry** (2 days) + +### Long-term Improvements + +1. **Config file support** (1 week) +2. **Runtime reconfiguration** (2 weeks) +3. **Telemetry dashboard** (1 month) + +--- + +## Testing Plan + +### Validation Steps + +1. **Baseline**: Run benchmarks with current ENV setup +2. **Consolidation**: Implement `HAKMEM_DEBUG` consolidation +3. **Regression**: Re-run benchmarks (should be identical) +4. **Cleanup**: Remove deprecated variables, re-test + +### Compatibility + +- **Keep old variables for 1 release** with deprecation warnings +- **Print migration guide** on deprecated variable use +- **Provide `hakmem-migrate-env.sh` script** + +--- + +## Migration Guide Example + +```bash +#!/bin/bash +# hakmem-migrate-env.sh - Migrate old ENV variables to new format + +# Before (Phase 1-4) +export HAKMEM_SFC_DEBUG=1 +export HAKMEM_ACE_DEBUG=1 +export HAKMEM_SUPER_REG_DEBUG=1 +export HAKMEM_SFC_STATS_DUMP=1 +export HAKMEM_TINY_COUNTERS_DUMP=1 + +# After (Phase 5 - Consolidated) +export HAKMEM_DEBUG=sfc,ace,superslab +export HAKMEM_STATS=sfc,counters +``` + +--- + +## Conclusion + +HAKMEM's 228 environment variables reflect its evolution from Phase 1-4 experimentation to Phase P2/P3 production hardening. While this flexibility enabled rapid prototyping, it now creates maintenance burden. + +**Recommended Actions**: +1. ✅ **Consolidate 65 debug/trace/stats variables** into 3 unified variables +2. ✅ **Remove 7 deprecated variables** immediately +3. ✅ **Create ENV variable registry** for validation and docs +4. ✅ **Target ~80 total variables** (65% reduction) +5. ✅ **Add config file support** for long-term usability + +**Timeline**: +- **Week 1**: Consolidate debug variables, remove deprecated +- **Week 2**: Add registry and validation +- **Week 3**: Document all variables, update README +- **Month 2**: Config file support (optional) + +This will transform HAKMEM from an expert-only allocator to a production-ready system with sane defaults and simple tuning. + +--- + +## Appendix A: Complete Variable List (228) + +See individual category sections above for full details. + +## Appendix B: getenv() Call Locations + +Total: 320 calls across 228 unique variables (average 1.4 calls per variable). + +**Hot path violations** (getenv in malloc/free): +- ❌ `hakmem_tiny_sfc.c:52` - SFC_DEBUG (read once, OK) +- ❌ `hakmem_elo.c:205-306` - HAKMEM_QUIET (10+ calls in loop!) **FIX CRITICAL** +- ❌ `box/hak_wrappers.inc.h:192` - FREE_WRAP_TRACE (in free wrapper) + +**Recommendation**: Cache all debug flags at init, never call `getenv()` after initialization completes. + +--- + +**End of Survey** diff --git a/docs/specs/ENV_VARS.md b/docs/specs/ENV_VARS.md index cc73af37..73ce6a6a 100644 --- a/docs/specs/ENV_VARS.md +++ b/docs/specs/ENV_VARS.md @@ -300,3 +300,43 @@ LD safety (for apps/LD_PRELOAD runs) - HAKMEM_TINY_BENCH_MODE=1 - ベンチ専用の簡素化採用パスを有効化。per-class 単一点の公開スロットを使用し、superslab_refill のスキャンと多段リング走査を回避。 - OOMガード(harvest/trim)は保持。A/B用途に限定してください。 + +--- + +ENV Cleanup Progress (2025-11) +============================== + +Phase 4a: Hot Path getenv Caching +--------------------------------- +COMPLETED: All getenv() calls in hot paths are now properly cached. + +Fixed files: +- `core/hakmem_elo.c` - Added `is_quiet()` helper with cached `g_quiet_mode` flag + - Was: 10+ getenv("HAKMEM_QUIET") calls inside loops + - Now: Single cached lookup at first call + +Verified (already correct): +- `core/hakmem_tiny_superslab.c` - Uses `static int g_*` caching pattern +- `core/hakmem_shared_pool.c` - Uses `static int xxx = -1` caching +- `core/hakmem_learner.c` - getenv outside main loop (thread start only) +- `core/box/pool_init_api.inc.h` - Init function (called once via pthread_once) +- `core/box/hak_core_init.inc.h` - Init function (called once via pthread_once) +- `core/box/hak_wrappers.inc.h` - Uses `static int on=-1` caching + +ENV Statistics (from ENV_VARIABLE_SURVEY.md): +- Total ENV variables: 228 +- Target after cleanup: ~80 (65% reduction) +- Categories: + - Core/Toggle: 15 (7%) + - Learning/Adaptive: 25 (11%) + - Performance Tuning: 45 (20%) + - Debug/Diagnostic: 65 (28%) ← Consolidation target + - Superslab/Backend: 25 (11%) + - TLS SLL (P2/P3): 20 (9%) + - Free Path Optimization: 15 (7%) + - Other: 23 (10%) + +Future Work (Phase 4b+): +- HAKMEM_DEBUG unified variable (consolidate 35 debug vars) +- HAKMEM_TRACE unified variable (consolidate 15 trace vars) +- HAKMEM_STATS unified variable (consolidate 15 dump vars)