hakmem/ENV_VARIABLE_SURVEY.md

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 1.5: Tiny/SuperSlab Core Toggles（Phase 9-2 以降）

Tiny allocator / SuperSlab 周りの「箱」と直結するトグルを整理し、
どれをデフォルト ON にし、どれを非常用スイッチとして残すかを明示する。

Variable	Default	Purpose	Recommendation
HAKMEM_TINY_USE_SUPERSLAB	1	Tiny が SuperSlab バックエンドを使うか	KEEP（デフォルト ON、0 は互換モード）
HAKMEM_TINY_SS_SHARED	2	Superslab backend モード（2=shared only,1=shared+legacy,0=legacy）	ARCHIVE_ONLY（mainline では shared-only 固定。ENV は archive/実験コード専用の歴史的ノブ）
HAKMEM_TINY_TLS_SLL	1	TLS SLL の有効/無効	KEEP（デフォルト ON、LD_PRELOAD 時のみ 0 に落とす）
HAKMEM_SS_EMPTY_REUSE	1	EMPTY Slab の優先再利用（Stage 0.5）	KEEP（デフォルト ON、0 はトラブル時の緊急 OFF）
HAKMEM_SS_EMPTY_SCAN_LIMIT	16→(検討:32/64)	EMPTY Slab のスキャン上限（per class）	KEEP（デフォルトは今後 32/64 に引き上げ候補）
HAKMEM_TINY_SLL_DRAIN_ENABLE	1	TLS SLL → slab freelist への周期Drainの ON/OFF	KEEP（core 経路、デフォルト ON）
HAKMEM_TINY_SLL_DRAIN_INTERVAL	2048	Drain を発火させる free 回数	KEEP（性能チューニング用）
HAKMEM_TINY_TENSION_DRAIN_ENABLE	1	shared_pool Stage2→0.5 再試行のための Tension Drain ON/OFF	KEEP（デフォルト ON、問題時の OFF スイッチ）
HAKMEM_TINY_TENSION_DRAIN_THRESHOLD	1024	Tension Drain を発火する TLS SLL の閾値	KEEP（性能チューニング用）

コメント:

• これらは 状態箱（Shared Pool/TLS SLL/SuperSlab）そのものの動作に直結するため、今後も残す前提。
• ただし HAKMEM_TINY_SS_SHARED は最終的に「2 固定」を標準とし、1/0 は 「非推奨だが互換/回帰調査用に残す」 ラベルを docs に付ける。

---

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	0	Enable CAP/WMAX learner thread	hakmem_learner.c	KEEP - Alias to HAKMEM_MODE (learning/research) with explicit override
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:

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	REMOVED - Deleted in Phase 4d cleanup
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) ※Phase 9-2 更新

Variable	Default	Purpose	Location	Recommendation
HAKMEM_TINY_USE_SUPERSLAB	1	Use SuperSlab backend	box/hak_core_init.inc.h	KEEP - Core（デフォルト ON）
HAKMEM_TINY_SS_SHARED	2	Shared SuperSlab pool mode (2=shared only,1=shared+legacy,0=legacy)	superslab_backend.c	KEEP - Core（2 を標準、1/0 は「非推奨/回帰調査用」）
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	ARCHIVE_ONLY（旧 unified backend のみで使用、現行 mainline では未使用の歴史的ノブ）

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	ARCHIVE_ONLY（C23 unified backend は archive 移行済み、mainline では無効）
HAKMEM_TINY_SS_LEGACY_HINT	0	Legacy hint	box/ss_legacy_backend_box.c	ARCHIVE_ONLY（legacy backend 専用、mainline では無効）
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)

   HAKMEM_TRACE=refill,free,wrap,superslab,mailbox,ring,ptr,route
   

2. HAKMEM_DEBUG (replaces 35 debug variables)

   HAKMEM_DEBUG=sfc,ace,superslab,lru,prewarm,acquire,free,sll,refill,heap,guard
   

3. HAKMEM_STATS (replaces 15 dump variables)

   HAKMEM_STATS=sfc,fast,counters,refill,front,trace,slim,guard,fault,invariant
   

---

Detailed Recommendations

Immediate Actions (Phase 1)

1. Remove Legacy Variables (7 vars)

# 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  # Removed (SIGUSR1 stats dump helper, Phase 4d)

2. Consolidate Debug Variables (50 vars → 1 var)

Create unified HAKMEM_DEBUG with comma-separated values:

Example:

// 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:

# 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:

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:

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:

# /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

#!/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