hakmem/docs/analysis/ENV_QUICK_REFERENCE.md

ENV Cleanup Quick Reference Card

✅ SAFE TO REMOVE NOW (1 var)

HAKMEM_TINY_FRONT_ENABLE_ULTRAHOT

Status: UltraHot feature completely removed in commit bcfb4f6b5 File: core/box/front_metrics_box.h:149 Action: Delete lines 148-152 (getenv check + usage) Risk: ZERO - Feature doesn't exist anymore

File: core/box/front_metrics_box.h
-        const char* env = getenv("HAKMEM_TINY_FRONT_ENABLE_ULTRAHOT");
-        if (env && atoi(env) != 0) {
-            g_tiny_front_enable_ultrahot = 1;
-        }

---

🔧 LOW HANGING FRUIT (Deduplication)

SFC_DEBUG - Called 4x, Should Be 1x

Problem: Same ENV var checked in 4 different files Solution: Single global variable

Step 1: Add to core/hakmem_tiny_sfc.c (line ~36)

int g_sfc_enabled = 1;
int g_sfc_debug = 0;  // ADD THIS

Step 2: Update init in core/hakmem_tiny_sfc.c (keep line 123):

if (env_debug && *env_debug && *env_debug != '0') {
    g_sfc_debug = 1;  // Set global once
    fprintf(stderr, "...

Step 3: Replace in 3 files:

File: core/tiny_alloc_fast_sfc.inc.h:114
-            free_debug_enabled = getenv("HAKMEM_SFC_DEBUG") ? 1 : 0;
+            extern int g_sfc_debug;
+            free_debug_enabled = g_sfc_debug;

File: core/tiny_free_fast.inc.h:104
-        free_ss_debug_enabled = getenv("HAKMEM_SFC_DEBUG") ? 1 : 0;
+        extern int g_sfc_debug;
+        free_ss_debug_enabled = g_sfc_debug;

File: core/box/hak_wrappers.inc.h:89
-        debug_enabled = (getenv("HAKMEM_SFC_DEBUG") != NULL) ? 1 : 0;
+        extern int g_sfc_debug;
+        debug_enabled = g_sfc_debug;

Savings: -3 getenv() calls on hot paths Risk: ZERO Impact: 4 files, ~10 lines total

---

⚠️ NEED VERIFICATION (21 vars)

Ask Maintainer/User:

1. Ultra Features (3 vars) - Experimental or Dead?

HAKMEM_TINY_ULTRA_SLIM           core/box/ultra_slim_alloc_box.h
HAKMEM_ULTRA_SLIM_STATS          core/box/ultra_slim_alloc_box.h
HAKMEM_TINY_ULTRA_DEBUG          core/box/hak_core_init.inc.h

Question: Are Ultra features still being developed/used?

Note: The following 4 vars were removed in commit 6b791b97d (2025-11-26):

HAKMEM_TINY_ULTRA_FRONT          (deleted)
HAKMEM_TINY_ULTRA_L0             (deleted)
HAKMEM_TINY_ULTRA_HEAP_DUMP      (deleted)
HAKMEM_TINY_ULTRA_PAGE_DUMP      (deleted)

2. Heap V2 (7 vars) - Active or Replaced?

HAKMEM_TINY_HEAP_V2_CLASS_MASK   core/front/tiny_heap_v2.h
HAKMEM_TINY_HEAP_V2_LEFTOVER_MODE core/front/tiny_heap_v2.h
HAKMEM_TINY_HEAP_V2_DEBUG        core/front/tiny_heap_v2.h
HAKMEM_TINY_HEAP_V2_STATS        core/tiny_alloc_fast.inc.h
HAKMEM_TINY_FRONT_V2             core/tiny_alloc_fast.inc.h
HAKMEM_TINY_FRONT_SLIM           core/tiny_alloc_fast.inc.h
HAKMEM_TINY_FRONT_DISABLE_HEAPV2 core/box/front_metrics_box.h

Question: Is Heap V2 frontend still used or replaced by newer code?

3. BG System (3 vars) - Keep or Deprecate?

HAKMEM_BATCH_BG                  core/hakmem_batch.c (g_bg_enabled=1)
HAKMEM_L25_BG_DRAIN              core/hakmem_l25_pool.c
HAKMEM_L25_BG_MS                 core/hakmem_l25_pool.c

Question: Is background drain still needed or deprecated?

Note: The following 2 Tiny BG vars were removed in commit 6b791b97d (2025-11-26):

HAKMEM_TINY_BG_REMOTE            (deleted)
HAKMEM_TINY_BG_REMOTE_BATCH      (deleted)

4. HotMag/SmallMag (1 var) - Used?

HAKMEM_TINY_SMALL_MAG            core/hakmem_tiny_smallmag.inc.h

Question: Is SmallMag still in use? (File exists, no getenv found for HotMag)

5. Ring/Debug (3 vars) - Needed?

HAKMEM_TINY_SLL_RING             core/box/tls_sll_box.h
HAKMEM_TINY_TRACE_RING           core/tiny_debug_ring.c
HAKMEM_TINY_DUMP_RING_ATEXIT    core/tiny_debug_ring.c

Question: Are Tiny SLL ring and debug ring different from L25 TLS ring?

---

✅ DEFINITELY KEEP (Active Features)

SFC - Shared Frontend Cache (6 vars) ✅

• Default: ON (g_sfc_enabled = 1)
• Compiled: hakmem_tiny_sfc.o in all binaries
• Vars: HAKMEM_SFC_ENABLE, CAPACITY, REFILL_COUNT, DEBUG, STATS_DUMP, CASCADE_PCT

TC - Thread Cache for Pool/L25 (10 vars) ✅

• Active for L25 and Pool allocations
• Vars: HAKMEM_L25_TC_, HAKMEM_MID_TC_, HAKMEM_TC_*

L25 TLS Ring (3 vars) ✅

• Active in L25 pool
• Vars: HAKMEM_POOL_TLS_RING, HAKMEM_RING_RETURN_DIV, HAKMEM_L25_RING_TRIGGER

BigCache (1 var) ✅

• Compiled: hakmem_bigcache.o
• Var: HAKMEM_BIGCACHE_L25

Total KEEP: 20 vars

---

📊 Summary Stats

Category	Count	Action
Safe to remove	1	Delete ULTRAHOT toggle
Deduplication	4	SFC_DEBUG consolidation
Need verification	21	Ask maintainer
Definitely keep	20	No action
Already removed	11	✅ Done
TOTAL	57

Current ENV vars: 221 Potential reduction: 1-22 vars (0.5%-10%)

---

🚀 Execution Order

1. Today: Remove HAKMEM_TINY_FRONT_ENABLE_ULTRAHOT (1 line, zero risk)
2. This week: Deduplicate SFC_DEBUG (4 files, low risk)
3. Next sprint: Verify 21 experimental vars with maintainer
4. Next release: Deprecate confirmed obsolete vars (doc + warnings)
5. Future release: Remove deprecated vars after 3-release cycle

---

📂 Files to Modify (Immediate Actions)

Priority 1: ULTRAHOT Removal

• core/box/front_metrics_box.h (lines 148-152)

Priority 2: SFC_DEBUG Dedup

• core/hakmem_tiny_sfc.c (add global, ~2 lines)
• core/tiny_alloc_fast_sfc.inc.h (change to extern, ~2 lines)
• core/tiny_free_fast.inc.h (change to extern, ~2 lines)
• core/box/hak_wrappers.inc.h (change to extern, ~2 lines)

Total: 5 files, ~10 lines of changes

---

🔍 Verification Template

For each experimental feature, check:

# 1. Is it compiled?
ls -la out/release/*.o | grep <feature>

# 2. Is it used in benchmarks?
grep -r "HAKMEM_<FEATURE>" scripts/ apps/ bench/

# 3. Default value?
grep -r "g_<feature>_enabled.*=" core/ --include="*.c"

# 4. Last commit?
git log --all --oneline --grep="<feature>" | head -5

If all NO → mark as OBSOLETE candidate