🚀 Auto-Allocator

🎯 One line of code. Platform-intelligent optimization. Zero configuration.

The smartest memory allocator for Rust that automatically selects the optimal allocator for your platform - delivering performance improvements where possible, and platform compliance where required.

🌟 Why Developers Choose Auto-Allocator

🎯 Smart Optimization for Every Platform

• Performance where it helps: 1.6x faster on multi-core Windows/macOS/Linux (Microsoft Research)
• Compliance where it matters: Respects Android/iOS official policies
• Efficiency everywhere: Optimal allocation from servers to microcontrollers

⚡ Effortless Integration

• Truly zero-config - just use auto_allocator; and you're optimized
• Universal compatibility - works on every Rust platform
• Production ready - handles platform differences automatically

🧠 Platform Intelligence

• Respects each platform's strengths - leverages native optimizations when better
• Hardware-aware - adapts to CPU cores and memory constraints
• Research-backed - every choice has technical justification

⚡ Quick Start

1. Add Dependency

[dependencies]
auto-allocator = "*"

2. Import and Use

use auto_allocator;  // 🎉 Done! Memory allocation is now optimized

fn main() {
    // Your existing code automatically benefits from optimal allocation
    let data = vec![1, 2, 3, 4, 5];
    let text = "Hello".repeat(1000);
    
    // No changes needed - just faster memory operations! 
    println!("🚀 High-performance allocation active!");
}

3. Verify Optimization (Optional)

use auto_allocator;

fn main() {
    let info = auto_allocator::get_allocator_info();
    println!("✅ Using: {:?}", info.allocator_type);
    println!("💡 {}", info.reason);
}

✨ That's literally all you need! Auto-Allocator handles everything else automatically.

🔬 How It Works

Auto-Allocator uses intelligent two-phase optimization:

📋 COMPILE TIME                    🚀 RUNTIME                    ✅ RESULT
┌─────────────────┐               ┌─────────────────┐           ┌─────────────────┐
│ Platform        │               │ CPU Core Count  │           │                 │
│ Detection       │──────────────▶│ Analysis        │──────────▶│ Optimal         │
│                 │               │                 │           │ Allocator       │
│ Compiler        │               │ Memory          │           │ Selection       │
│ Analysis        │──────────────▶│ Detection       │──────────▶│                 │
│                 │               │                 │           │                 │
│ Feature         │               │ Hardware        │           │                 │
│ Availability    │──────────────▶│ Optimization    │──────────▶│                 │
└─────────────────┘               └─────────────────┘           └─────────────────┘

🎯 90% of decisions made at compile-time for zero runtime overhead
⚡ Only high-performance platforms need runtime CPU detection

🎯 Platform-Specific Selection

🚀 Performance Results

When mimalloc is selected (Windows/macOS/Linux multi-core):

• 1.6x faster allocation in multi-threaded scenarios (Microsoft Research)
• Reduced lock contention through free-list sharding
• Better cache locality and lower memory fragmentation

Test it yourself:

cargo bench  # Benchmark your specific workload

Key insight: Auto-Allocator delivers performance improvements where they matter, while respecting platform policies elsewhere.

🛡️ Security Features

🔒 When Available (Platform-Dependent)

Security features are only available on platforms that use mimalloc-secure:

# Only effective on Windows/macOS/Linux with mimalloc support
[dependencies]
auto-allocator = { version = "*", features = ["secure"] }

🎯 Platform-Specific Security

📊 Security Trade-offs

💡 Key insight: Many platforms already have excellent built-in security - Auto-Allocator respects and leverages these instead of overriding them.

🛠️ Advanced Usage

🔍 Check What's Being Used

use auto_allocator;

fn main() {
    // 🔍 Inspect current allocator selection
    let info = auto_allocator::get_allocator_info();
    println!("🚀 Active: {:?}", info.allocator_type);
    println!("💡 Why: {}", info.reason);
    
    // 📈 System specifications  
    println!("🖥️  Hardware: {} cores, {} RAM", 
             info.system_info.cpu_cores,
             auto_allocator::format_memory_size(info.system_info.total_memory_bytes));
    
    // ✅ Validate optimal configuration
    let (is_optimal, suggestion) = auto_allocator::check_allocator_optimization();
    if !is_optimal {
        println!("⚠️  Optimization tip: {}", suggestion.unwrap());
    }
    
    // 🎯 Get platform-specific recommendations
    let (recommended, reason) = auto_allocator::get_recommended_allocator();
    println!("💯 Recommended: {:?} - {}", recommended, reason);
}

🔬 Technical Deep-Dive

🏆 Why mimalloc Dominates Performance

🎯 Peer-Reviewed Research:

• Microsoft Research Study: 1.6x faster than jemalloc in production

• Free-list sharding: Eliminates lock contention in multi-threaded applications

• Cache-conscious design: Better memory locality = faster access patterns

• Battle-tested: Powers Microsoft Azure, Office 365, and Windows services

💡 Examples & Tutorials

Explore real-world usage in the examples/ directory:

📄 License

Flexible licensing for maximum compatibility:

• MIT License - Permissive, commercial-friendly
• Apache License 2.0 - Enterprise-preferred, patent protection
• Mozilla Public License 2.0 - Copyleft alternative

Choose the license that best fits your project!

🎓 Research & References

📚 Core Research

• mimalloc: Free List Sharding in Action - Microsoft Research
• A Scalable Concurrent malloc(3) Implementation - Jason Evans (Facebook)

🏢 Platform Documentation

• Android Scudo Hardened Allocator - Android AOSP
• Apple Memory Management Guidelines - Apple Developer