hakmem/docs/analysis/LARGE_FILES_ANALYSIS.md

Large Files Analysis Report (1000+ Lines)

HAKMEM Memory Allocator Codebase

Date: 2025-11-06

---

EXECUTIVE SUMMARY

Large Files Identified (1000+ lines)

Rank	File	Lines	Functions	Avg Lines/Func	Priority
1	hakmem_pool.c	2,592	65	40	CRITICAL
2	hakmem_tiny.c	1,765	57	31	CRITICAL
3	hakmem.c	1,745	29	60	HIGH
4	hakmem_tiny_free.inc	1,711	10	171	CRITICAL
5	hakmem_l25_pool.c	1,195	39	31	HIGH

Total Lines in Large Files: 9,008 / 32,175 (28% of codebase)

---

DETAILED ANALYSIS

1. hakmem_pool.c (2,592 lines) - L2 Hybrid Pool Implementation

Classification: Core Pool Manager | Refactoring Priority: CRITICAL

Primary Responsibilities

• Size Classes: 2-32KB allocation (5 fixed classes + 2 dynamic)
• TLS Caching: Ring buffer + bump-run pages (3 active pages per class)
• Page Registry: MidPageDesc hash table (2048 buckets) for ownership tracking
• Thread Cache: MidTC ring buffers per thread
• Freelist Management: Per-class, per-shard global freelists
• Background Tasks: DONTNEED batching, policy enforcement

Code Structure

Lines 1-45:      Header comments + config documentation (44 lines)
Lines 46-66:     Includes (14 headers)
Lines 67-200:    Internal data structures (TLS ring, page descriptors)
Lines 201-1100:  Page descriptor registry (hash, lookup, adopt)
Lines 1101-1800: Thread cache management (TLS operations)
Lines 1801-2500: Freelist operations (alloc, free, refill)
Lines 2501-2592: Public API + sizing functions (hak_pool_alloc, hak_pool_free)

Key Functions (65 total)

High-level (10):

• hak_pool_alloc() - Main allocation entry point
• hak_pool_free() - Main free entry point
• hak_pool_alloc_fast() - TLS fast path
• hak_pool_free_fast() - TLS fast path
• hak_pool_set_cap() - Capacity tuning
• hak_pool_get_stats() - Statistics
• hak_pool_trim() - Memory reclamation
• mid_desc_lookup() - Page ownership lookup
• mid_tc_alloc_slow() - Refill from global
• mid_tc_free_slow() - Spill to global

Hot path helpers (15):

• mid_tc_alloc_fast() - Ring pop
• mid_tc_free_slow() - Ring push
• mid_desc_register() - Page ownership
• mid_page_inuse_inc/dec() - Tracking
• mid_batch_drain() - Background processing

Internal utilities (40):

• Hash functions, initialization, thread local ops

Includes (14)

hakmem_pool.h, hakmem_config.h, hakmem_internal.h,
hakmem_syscall.h, hakmem_prof.h, hakmem_policy.h,
hakmem_debug.h + 7 system headers

Cross-File Dependencies

Calls from (3 files):

• hakmem.c - Main entry point, dispatches to pool
• hakmem_ace.c - Metrics collection
• hakmem_learner.c - Auto-tuning feedback

Called by hakmem.c to allocate:

• 8-32KB size range
• Mid-range allocation tier

Complexity Metrics

• Cyclomatic Complexity: 40+ branches/loops (high)
• Mutable State: 12+ global/thread-local variables
• Lock Contention: per-(class,shard) mutexes (fine-grained, good)
• Code Duplication: TLS ring buffer pattern repeated (alloc/free paths)

Refactoring Recommendations

HIGH PRIORITY - Split into 3 modules:

1. mid_pool_cache.c (600 lines)

   • TLS ring buffer management
   • Page descriptor registry
   • Thread local state management
   • Functions: mid_tc_, mid_desc_

2. mid_pool_alloc.c (800 lines)

   • Allocation fast/slow paths
   • Refill from global freelist
   • Bump-run page management
   • Functions: hak_pool_alloc*, mid_tc_alloc_slow, refill_*

3. mid_pool_free.c (600 lines)

   • Free paths (fast/slow)
   • Spill to global freelist
   • Page tracking (in_use counters)
   • Functions: hak_pool_free*, mid_tc_free_slow, drain_*

4. Keep in mid_pool_core.c (200 lines)

   • Public API (hak_pool_alloc/free)
   • Initialization
   • Statistics
   • Policy enforcement

Expected Benefits:

• Per-module responsibility clarity
• Easier testing of alloc vs. free paths
• Reduced compilation time (modular linking)
• Better code reuse with L25 pool (currently 1195 lines, similar structure)

---

2. hakmem_tiny.c (1,765 lines) - Tiny Pool Orchestrator

Classification: Core Allocator | Refactoring Priority: CRITICAL

Primary Responsibilities

• Size Classes: 8-128B allocation (4 classes + overflow)
• SuperSlab Management: Multi-slab owner tracking
• Refill Orchestration: TLS → Magazine → SuperSlab cascading
• Statistics: Per-class allocation/free tracking
• Lifecycle: Initialization, trimming, flushing
• Compatibility: Ultra-Simple, Metadata, Box-Refactor fast paths

Code Structure

Lines 1-50:      Includes (35 headers - HUGE dependency list)
Lines 51-200:    Configuration macros + debug counters
Lines 201-400:   Function declarations (forward refs)
Lines 401-1000:  Main allocation path (7 layers of fallback)
Lines 1001-1300: Free path implementations (SuperSlab + Magazine)
Lines 1301-1500: Helper functions (stats, lifecycle)
Lines 1501-1765: Include guards + module wrappers

High Dependencies

35 #include statements (unusual for a .c file):

• hakmem_tiny.h, hakmem_tiny_config.h
• hakmem_tiny_superslab.h, hakmem_super_registry.h
• hakmem_tiny_magazine.h, hakmem_tiny_batch_refill.h
• hakmem_tiny_stats.h, hakmem_tiny_stats_api.h
• hakmem_tiny_query_api.h, hakmem_tiny_registry_api.h
• tiny_tls.h, tiny_debug.h, tiny_mmap_gate.h
• tiny_debug_ring.h, tiny_route.h, tiny_ready.h
• hakmem_tiny_tls_list.h, hakmem_tiny_remote_target.h
• hakmem_tiny_bg_spill.h + more

Problem: Acts as a "glue layer" pulling in 35 modules - indicates poor separation of concerns

Key Functions (57 total)

Top-level entry (4):

• hak_tiny_alloc() - Main allocation
• hak_tiny_free() - Main free
• hak_tiny_trim() - Memory reclamation
• hak_tiny_get_stats() - Statistics

Fast paths (8):

• tiny_alloc_fast() - TLS pop (3-4 instructions)
• tiny_free_fast() - TLS push (3-4 instructions)
• superslab_tls_bump_fast() - Bump-run fast path
• hak_tiny_alloc_ultra_simple() - Alignment-based fast path
• hak_tiny_free_ultra_simple() - Alignment-based free

Slow paths (15):

• tiny_slow_alloc_fast() - Magazine refill
• tiny_alloc_superslab() - SuperSlab adoption
• superslab_refill() - SuperSlab replenishment
• hak_tiny_free_superslab() - SuperSlab free
• Batch refill helpers

Helpers (30):

• Magazine management
• Registry lookups
• Remote queue handling
• Debug helpers

Includes Analysis

Problem Modules (should be in separate files):

1. hakmem_tiny.h - Type definitions
2. hakmem_tiny_config.h - Configuration macros
3. hakmem_tiny_superslab.h - SuperSlab struct
4. hakmem_tiny_magazine.h - Magazine type
5. tiny_tls.h - TLS operations

Indicator: If hakmem_tiny.c needs 35 headers, it's coordinating too many subsystems.

Refactoring Recommendations

HIGH PRIORITY - Extract coordination layer:

The 1765 lines are organized as:

1. Alloc path (400 lines) - 7-layer cascade
2. Free path (400 lines) - Local/Remote/SuperSlab branches
3. Magazine logic (300 lines) - Batch refill/spill
4. SuperSlab glue (300 lines) - Adoption/lookup
5. Misc helpers (365 lines) - Stats, lifecycle, debug

Recommended split:

hakmem_tiny_core.c (300 lines)
  - hak_tiny_alloc() dispatcher
  - hak_tiny_free() dispatcher
  - Fast path shortcuts (inlined)
  - Recursion guard

hakmem_tiny_alloc.c (350 lines)
  - Allocation cascade logic
  - Magazine refill path
  - SuperSlab adoption

hakmem_tiny_free.inc (already 1711 lines!)
  - Should be split into:
    * tiny_free_local.inc (500 lines)
    * tiny_free_remote.inc (500 lines)
    * tiny_free_superslab.inc (400 lines)

hakmem_tiny_stats.c (already 818 lines)
  - Keep separate (good design)

hakmem_tiny_superslab.c (already 821 lines)
  - Keep separate (good design)

Key Issue: The file at 1765 lines is already at the limit. The #include count (35!) suggests it should already be split.

---

3. hakmem.c (1,745 lines) - Main Allocator Dispatcher

Classification: API Layer | Refactoring Priority: HIGH

Primary Responsibilities

• malloc/free interposition: Standard C malloc hooks
• Dispatcher: Routes to Pool/Tiny/Whale/L25 based on size
• Initialization: One-time setup, environment parsing
• Configuration: Policy enforcement, cap tuning
• Statistics: Global KPI tracking, debugging output

Code Structure

Lines 1-60:      Includes (38 headers)
Lines 61-200:    Configuration constants + globals
Lines 201-400:   Helper macros + initialization guards
Lines 401-600:   Feature detection (jemalloc, LD_PRELOAD)
Lines 601-1000:  Allocation dispatcher (hakmem_alloc_at)
Lines 1001-1300: malloc/calloc/realloc/posix_memalign wrappers
Lines 1301-1500: free wrapper
Lines 1501-1745: Shutdown + statistics + debugging

Routing Logic

malloc(size)
  ├─ size <= 128B → hak_tiny_alloc()
  ├─ size 128-32KB → hak_pool_alloc()
  ├─ size 32-1MB → hak_l25_alloc()
  └─ size > 1MB → hak_whale_alloc() or libc_malloc

Key Functions (29 total)

Public API (10):

• malloc() - Standard hook
• free() - Standard hook
• calloc() - Zeroed allocation
• realloc() - Size change
• posix_memalign() - Aligned allocation
• hak_alloc_at() - Internal dispatcher
• hak_free_at() - Internal free dispatcher
• hak_init() - Initialization
• hak_shutdown() - Cleanup
• hak_get_kpi() - Metrics

Initialization (5):

• Environment variable parsing
• Feature detection (jemalloc, LD_PRELOAD)
• One-time setup
• Recursion guard initialization
• Statistics initialization

Configuration (8):

• Policy enforcement
• Cap tuning
• Strategy selection
• Debug mode control

Statistics (6):

• hak_print_stats() - Output summary
• hak_get_kpi() - Query metrics
• Latency measurement
• Page fault tracking

Includes (38)

Problem areas:

• Too many subsystem includes for a dispatcher
• Should import via public headers only, not internals

Suggests: Dispatcher trying to manage too much state

Refactoring Recommendations

MEDIUM-HIGH PRIORITY - Extract dispatcher + config:

Split into:

1. hakmem_api.c (400 lines)

   • malloc/free/calloc/realloc/memalign
   • Recursion guard
   • Initialization
   • LD_PRELOAD safety checks

2. hakmem_dispatch.c (300 lines)

   • hakmem_alloc_at()
   • Size-based routing
   • Feature dispatch (strategy selection)

3. hakmem_config.c (350 lines, already partially exists)

   • Configuration management
   • Environment parsing
   • Policy enforcement

4. hakmem_stats.c (300 lines)

   • Statistics collection
   • KPI tracking
   • Debug output

Better organization:

• hakmem.c should focus on being the dispatch frontend
• Config management should be separate
• Stats collection should be a module
• Each allocator (pool, tiny, l25, whale) is responsible for its own stats

---

4. hakmem_tiny_free.inc (1,711 lines) - Free Path Orchestration

Classification: Core Free Path | Refactoring Priority: CRITICAL

Primary Responsibilities

• Ownership Detection: Determine if pointer is TLS-owned
• Local Free: Return to TLS freelist (TLS match)
• Remote Free: Queue for owner thread (cross-thread)
• SuperSlab Free: Adopt SuperSlab-owned blocks
• Magazine Integration: Spill to magazine when TLS full
• Safety Checks: Validation (debug mode only)

Code Structure

Lines 1-10:      Includes (7 headers)
Lines 11-100:    Helper functions (queue checks, validates)
Lines 101-400:   Local free path (TLS-owned)
Lines 401-700:   Remote free path (cross-thread)
Lines 701-1000:  SuperSlab free path (adoption)
Lines 1001-1400: Magazine integration (spill logic)
Lines 1401-1711: Utilities + validation helpers

Unique Feature: Included File (.inc)

• NOT a standalone .c file
• Included into hakmem_tiny.c
• Suggests tight coupling with tiny allocator

Problem: .inc files at 1700+ lines should be split into multiple .inc files or converted to modular .c files with headers

Key Functions (10 total)

Main entry (3):

• hak_tiny_free() - Dispatcher
• hak_tiny_free_with_slab() - Pre-calculated slab
• hak_tiny_free_ultra_simple() - Alignment-based

Fast paths (4):

• Local free to TLS (most common)
• Magazine spill (when TLS full)
• Quick validation checks
• Ownership detection

Slow paths (3):

• Remote free (cross-thread queue)
• SuperSlab adoption (TLS migrated)
• Safety checks (debug mode)

Average Function Size: 171 lines

Problem indicators:

• Functions way too large (should average 20-30 lines)
• Deepest nesting level: ~6-7 levels
• Mixing of high-level control flow with low-level details

Complexity

Free path decision tree (simplified):
  if (local thread owner)
    → Free to TLS
      if (TLS full)
        → Spill to magazine
          if (magazine full)
            → Drain to SuperSlab
  else if (remote thread owner)
    → Queue for remote thread
      if (queue full)
        → Fallback strategy
  else if (SuperSlab-owned)
    → Adopt SuperSlab
      if (already adopted)
        → Free to SuperSlab freelist
      else
        → Register ownership
  else
    → Error/unknown pointer

Refactoring Recommendations

CRITICAL PRIORITY - Split into 4 modules:

1. tiny_free_local.inc (500 lines)

   • TLS ownership detection
   • Local freelist push
   • Quick validation
   • Magazine spill threshold

2. tiny_free_remote.inc (500 lines)

   • Remote thread detection
   • Queue management
   • Fallback strategies
   • Cross-thread communication

3. tiny_free_superslab.inc (400 lines)

   • SuperSlab ownership detection
   • Adoption logic
   • Freelist publishing
   • Superslab refill interaction

4. tiny_free_dispatch.inc (300 lines, new)

   • Dispatcher logic
   • Ownership classification
   • Route selection
   • Safety checks

Expected benefits:

• Each module ~300-500 lines (manageable)
• Clear separation of concerns
• Easier debugging (narrow down which path failed)
• Better testability (unit test each path)
• Reduced cyclomatic complexity per function

---

5. hakmem_l25_pool.c (1,195 lines) - Large Pool (64KB-1MB)

Classification: Core Pool Manager | Refactoring Priority: HIGH

Primary Responsibilities

• Size Classes: 64KB-1MB allocation (5 classes)
• Bundle Management: Multi-page bundles
• TLS Caching: Ring buffer + active run (bump-run)
• Freelist Sharding: Per-class, per-shard (64 shards/class)
• MPSC Queues: Cross-thread free handling
• Background Processing: Soft CAP guidance

Code Structure

Lines 1-48:      Header comments (docs)
Lines 49-80:     Includes (13 headers)
Lines 81-170:    Internal structures + TLS state
Lines 171-500:   Freelist management (per-shard)
Lines 501-900:   Allocation paths (fast/slow/refill)
Lines 901-1100:  Free paths (local/remote)
Lines 1101-1195: Public API + statistics

Key Functions (39 total)

High-level (8):

• hak_l25_alloc() - Main allocation
• hak_l25_free() - Main free
• hak_l25_alloc_fast() - TLS fast path
• hak_l25_free_fast() - TLS fast path
• hak_l25_set_cap() - Capacity tuning
• hak_l25_get_stats() - Statistics
• hak_l25_trim() - Memory reclamation

Alloc paths (8):

• Ring pop (fast)
• Active run bump (fast)
• Freelist refill (slow)
• Bundle allocation (slowest)

Free paths (8):

• Ring push (fast)
• LIFO overflow (when ring full)
• MPSC queue (remote)
• Bundle return (slowest)

Internal utilities (15):

• Ring management
• Shard selection
• Statistics
• Initialization

Includes (13)

• hakmem_l25_pool.h - Type definitions
• hakmem_config.h - Configuration
• hakmem_internal.h - Common types
• hakmem_syscall.h - Syscall wrappers
• hakmem_prof.h - Profiling
• hakmem_policy.h - Policy enforcement
• hakmem_debug.h - Debug utilities

Pattern: Similar to hakmem_pool.c (MidPool)

Comparison:

Aspect	MidPool (2592)	LargePool (1195)
Size Classes	5 fixed + 2 dynamic	5 fixed
TLS Structure	Ring + 3 active pages	Ring + active run
Sharding	Per-(class,shard)	Per-(class,shard)
Code Duplication	High (from L25)	Base for duplication
Functions	65	39

Observation: L25 Pool is 46% smaller, suggesting good recent refactoring OR incomplete implementation

Refactoring Recommendations

MEDIUM PRIORITY - Extract shared patterns:

1. Extract pool_core library (300 lines)

   • Ring buffer management
   • Sharded freelist operations
   • Statistics tracking
   • MPSC queue utilities

2. Use for both MidPool and LargePool:

   • Reduces duplication (saves ~200 lines in each)
   • Standardizes behavior
   • Easier to fix bugs once, deploy everywhere

3. Per-pool customization (600 lines per pool)

   • Size-specific logic
   • Bump-run vs. active pages
   • Class-specific policies

---

SUMMARY TABLE: Refactoring Priority Matrix

File	Lines	Functions	Avg/Func	Incohesion	Priority	Est. Effort	Benefit
hakmem_tiny_free.inc	1,711	10	171	EXTREME	CRITICAL	HIGH	High (171→30 avg)
hakmem_pool.c	2,592	65	40	HIGH	CRITICAL	MEDIUM	Med (extract 3 modules)
hakmem_tiny.c	1,765	57	31	HIGH	CRITICAL	HIGH	High (35 includes→5)
hakmem.c	1,745	29	60	HIGH	HIGH	MEDIUM	High (dispatcher clarity)
hakmem_l25_pool.c	1,195	39	31	MEDIUM	HIGH	LOW	Med (extract pool_core)

---

RECOMMENDATIONS BY PRIORITY

Tier 1: CRITICAL (do first)

1. hakmem_tiny_free.inc - Split into 4 modules

   • Reduces average function from 171→~80 lines
   • Enables unit testing per path
   • Reduces cyclomatic complexity

2. hakmem_pool.c - Extract 3 modules

   • Reduces responsibility from "all pool ops" to "cache management" + "alloc" + "free"
   • Easier to reason about
   • Enables parallel development

3. hakmem_tiny.c - Reduce to 2-3 core modules

   • Cut 35 includes down to 5-8
   • Reduces from 1765→400-500 core file
   • Leaves helpers in dedicated modules

Tier 2: HIGH (after Tier 1)

4. hakmem.c - Extract dispatcher + config

   • Split into 4 modules (api, dispatch, config, stats)
   • Reduces from 1745→400-500 each
   • Better testability

5. hakmem_l25_pool.c - Extract pool_core library

   • Shared code with MidPool
   • Reduces code duplication

Tier 3: MEDIUM (future)

6. Extract pool_core library from MidPool/LargePool
7. Create hakmem_tiny_alloc.c (currently split across files)
8. Consolidate statistics collection into unified framework

---

ESTIMATED IMPACT

Code Metrics Improvement

Before:

• 5 files over 1000 lines
• 35 includes in hakmem_tiny.c
• Average function in tiny_free.inc: 171 lines

After Tier 1:

• 0 files over 1500 lines
• Max function: ~80 lines
• Cyclomatic complexity: -40%

Maintainability Score

• Before: 4/10 (large monolithic files)
• After Tier 1: 6.5/10 (clear module boundaries)
• After Tier 2: 8/10 (modular, testable design)

Development Speed

• Finding bugs: -50% time (smaller files to search)
• Adding features: -30% time (clear extension points)
• Testing: -40% time (unit tests per module)

---

BOX THEORY INTEGRATION

Current Box Modules (in core/box/):

• free_local_box.c - Local thread free
• free_publish_box.c - Publishing freelist
• free_remote_box.c - Remote queue
• front_gate_box.c - Fast path entry
• mailbox_box.c - MPSC queue management

Recommended Box Alignment:

1. Rename tiny_free_*.inc → Box 6A, 6B, 6C, 6D
2. Create pool_core_box.c for shared functionality
3. Add pool_cache_box.c for TLS management

---

NEXT STEPS

1. Week 1: Extract tiny_free paths (4 modules)
2. Week 2: Refactor pool.c (3 modules)
3. Week 3: Consolidate tiny.c (reduce includes)
4. Week 4: Split hakmem.c (dispatcher pattern)
5. Week 5: Extract pool_core library

Estimated total effort: 5 weeks of focused refactoring Expected outcome: 50% improvement in code maintainability