A conservative mark-and-sweep garbage collector implementation for the V programming language with heap partitioning, automatic heap growth, and advanced memory management features.

• Conservative Mark-and-Sweep: Implements the classic mark-and-sweep garbage collection algorithm
• Heap Partitioning: Reduces memory fragmentation using multiple heap partitions with size-class optimization
• Automatic Collection: Triggers garbage collection automatically based on configurable heap usage thresholds
• Incremental Collection: Low-latency collection that processes one partition at a time

• Automatic Heap Growth: Dynamically expands heap size when memory pressure increases
• Configurable Growth Parameters: Customizable growth factors, minimum growth increments, and maximum heap limits
• Smart Growth Logic: Prevents excessive growth through intelligent allocation failure detection
• Memory Compaction: Optional compaction to eliminate fragmentation after growth events

• Size-Class Allocation: Optimized allocation paths for frequently used small objects
• Free Block Coalescing: Merges adjacent free blocks to reduce fragmentation
• Conservative Root Scanning: Efficient scanning of stack, registers, and user-defined roots
• Allocation Tracking: Optional debugging and profiling support

• Detailed Statistics: Comprehensive GC performance metrics and heap utilization data
• Growth Monitoring: Track heap expansion events, fragmentation ratios, and allocation patterns
• Heap Validation: Debug mode with integrity checking and layout visualization
• Performance Profiling: Allocation rate tracking and collection timing analysis

git clone https://github.com/mike-ward/gc

import gc

// Initialize garbage collector with default settings
mut collector := gc.new_garbage_collector(32 * 1024 * 1024) // 32MB
defer { collector.destroy() }

// Allocate memory
ptr := collector.alloc(1024)

// Add roots for persistent data
mut global_data := [100]int{}
collector.add_root(voidptr(&global_data[0]), sizeof(global_data))

// Get statistics
stats := collector.get_stats()
println('GC runs: ${stats.gc_count}, Heap used: ${stats.heap_used}')

import gc

// Configure a growable heap collector
config := gc.GCConfig{
    heap_size:          16 * 1024 * 1024,     // Start with 16MB
    max_heap_size:      256 * 1024 * 1024,    // Can grow up to 256MB
    enable_heap_growth: true,
    growth_factor:      1.5,                  // Grow by 50% each time
    min_growth_size:    8 * 1024 * 1024,      // Minimum 8MB increment
    trigger_threshold:  0.8,                  // Trigger GC at 80% usage
    enable_coalescing:  true,
    debug_mode:         true
}

mut collector := gc.new_garbage_collector_with_config(config)
defer { collector.destroy() }

// Monitor heap growth
growth_stats := collector.get_growth_stats()
println('Heap: ${growth_stats.current_size / (1024*1024)}MB / ${growth_stats.max_size / (1024*1024)}MB')

// Optimized allocation for small objects
ptr1 := collector.alloc_optimized(64)

// Incremental collection for low latency
collector.collect_incremental()

// Force heap growth for testing
if collector.force_grow_heap() {
    println('Heap successfully expanded!')
}

// Memory compaction
collector.compact()

// Detailed monitoring
detailed_stats := collector.get_detailed_stats()
println('Fragmentation: ${detailed_stats.fragmentation_ratio:.2f}%')

1. Mark Phase: Scans from root set (stack, registers, user-defined roots) and marks all reachable objects
2. Sweep Phase: Frees all unmarked objects and coalesces adjacent free blocks
3. Incremental Mode: Processes one partition per collection cycle for reduced pause times

The heap can automatically expand when memory pressure increases:

• Growth Triggers: Allocation failures and high memory usage (>90% after GC)
• Size Calculation: Uses configurable growth factors and minimum increment sizes
• Pointer Safety: All internal pointers are safely updated after heap relocation
• Growth Limits: Respects maximum heap size to prevent runaway memory usage

The heap is divided into multiple partitions to:

• Reduce fragmentation through size-class based allocation
• Enable incremental collection with bounded pause times
• Improve cache locality for better performance
• Support future parallel collection implementations

Since V doesn't provide complete type information at runtime, the collector:

• Treats any pointer-sized aligned value as a potential pointer
• Scans the entire stack and registers conservatively
• Maintains user-defined root sets for known pointer locations
• Uses heap bounds checking to validate potential pointers

pub struct GCConfig {
    // Basic heap settings
    heap_size:           u32 = 32 * 1024 * 1024    // Initial heap size
    max_heap_size:       u32 = 512 * 1024 * 1024   // Maximum heap size
    num_partitions:      u32 = 8                   // Number of heap partitions

    // Collection settings
    trigger_threshold:   f64 = 0.75                // GC trigger percentage
    enable_coalescing:   bool = true               // Enable free block merging
    enable_compaction:   bool = false              // Enable memory compaction

    // Growth settings
    enable_heap_growth:  bool = true               // Enable automatic growth
    growth_factor:       f64 = 2.0                // Growth multiplier
    min_growth_size:     u32 = 4 * 1024 * 1024    // Minimum growth increment

    // Debugging and profiling
    debug_mode:          bool = false              // Enable debug output
    allocation_tracking: bool = false              // Track allocations
}

The repository includes comprehensive examples:

• example.v - Basic allocation, root management, and statistics
• growable.v - Complete growable heap demonstration with multiple scenarios

1. Basic Allocation - Simple object allocation within initial heap
2. Heap Growth - Automatic expansion when memory pressure increases
3. Multiple Growth Cycles - Repeated expansions under sustained pressure
4. Mixed Allocations - Various object sizes and allocation patterns
5. Incremental Collection - Low-latency collection with heap growth
6. Performance Comparison - Fixed vs. growable heap benchmarks

The garbage collector is optimized for:

• Incremental Collection: Bounded pause times through partition-based collection
• Smart Growth: Minimizes allocation stalls through predictive growth
• Size-Class Optimization: Fast paths for common allocation sizes

• Reduced Fragmentation: Heap partitioning and coalescing minimize waste
• Conservative Scanning: Efficient pointer identification and traversal
• Batch Operations: Optimized mark and sweep phases

• Automatic Scaling: Heap grows and shrinks based on application needs
• Fragmentation Control: Compaction and coalescing maintain heap density
• Partition Balance: Even distribution across size classes

• Allocation Rate: 1M+ allocations/second for small objects
• Collection Pause: <1ms for incremental collection per partition
• Growth Overhead: <100μs for heap expansion events
• Memory Efficiency: <10% fragmentation under normal load

// Basic statistics
stats := collector.get_stats()

// Detailed analysis
detailed := collector.get_detailed_stats()

// Growth monitoring
growth := collector.get_growth_stats()

• Heap Layout Visualization: collector.print_heap_layout()
• Integrity Validation: collector.validate_heap()
• Allocation Tracking: Optional per-allocation metadata
• Growth Event Logging: Automatic logging of expansion events

# Run all tests
v test .

MIT License - see LICENSE file for details.

Contributions are welcome! Please read the contributing guidelines and ensure all tests pass before submitting pull requests.

Future enhancements planned:

• Parallel Collection: Multi-threaded mark and sweep phases
• Generational GC: Separate young and old object spaces
• Write Barriers: Support for more sophisticated collection algorithms
• Platform Integration: Direct integration with V compiler runtime
• Advanced Compaction: Moving collection with reference updating