MemoryUsageLimitation

public struct MemoryUsageLimitation

A high-performance, in-memory key-value cache with configurable thread safety and memory management.

Core Features

• TTL (Time-to-Live) Expiration: Automatic cleanup of expired entries
• Priority-Based Eviction: Higher priority entries are retained longer during eviction
• LRU (Least Recently Used) Eviction: Within priority levels, least recently used entries are evicted first
• Null Element Caching: Support for caching null/nil elements with separate TTL configuration
• External Key Validation: Customizable key validation function set at initialization
• TTL Randomization: Prevents cache stampede by randomizing expiration times
• Configurable Thread Safety: Optional DispatchSemaphore synchronization for concurrent access
• Memory Usage Tracking: Configurable memory limits with automatic eviction

Thread Safety

• Synchronized Mode (enableThreadSynchronization=true): All operations are thread-safe using DispatchSemaphore
• Non-Synchronized Mode (enableThreadSynchronization=false): No synchronization; caller must ensure thread safety

Performance Characteristics

• Time Complexity: O(1) average case for get/set operations
• Memory Efficiency: Configurable capacity and memory limits
• Automatic Expiration: Background cleanup of expired entries
• Eviction Policy: Priority-based LRU eviction with memory limit enforcement

Example Usage

// Thread-synchronized cache with custom validation and memory limits
let imageCache = MemoryCache<String, UIImage>(
    configuration: .init(
        enableThreadSynchronization: true,
        memoryUsageLimitation: .init(capacity: 1000, memory: 500), // 500MB limit
        defaultTTL: 3600, // 1 hour
        keyValidator: { $0.hasPrefix("https://") },
        costProvider: { image in
            guard let cgImage = image.cgImage else { return 0 }
            return cgImage.bytesPerRow * cgImage.height // Returns bytes
        }
    )
)

// Non-synchronized cache for single-threaded scenarios
let fastCache = MemoryCache<String, Int>(
    configuration: .init(
        enableThreadSynchronization: false,
        memoryUsageLimitation: .init(capacity: 500, memory: 100)
    )
)