MemoryKit API Reference¶

dependencies: [
    .package(path: "path/to/substation")
],
targets: [
    .target(
        name: "YourTarget",
        dependencies: [
            .product(name: "MemoryKit", package: "substation")
        ]
    )
]

import MemoryKit

// Initialize MemoryKit with default configuration
let memoryKit = await MemoryKit()

// Or with custom configuration
let config = MemoryKit.Configuration(
    memoryManagerConfig: MemoryManager.Configuration(
        maxCacheSize: 5000,
        maxMemoryBudget: 100 * 1024 * 1024, // 100MB
        cleanupInterval: 600.0 // 10 minutes
    )
)
let memoryKit = await MemoryKit(configuration: config)

public actor MemoryKit {
    public init(configuration: Configuration = Configuration()) async
}

public struct Configuration: Sendable {
    public let memoryManagerConfig: MemoryManager.Configuration
    public let performanceMonitorConfig: PerformanceMonitor.Configuration

    public init(
        memoryManagerConfig: MemoryManager.Configuration = MemoryManager.Configuration(),
        performanceMonitorConfig: PerformanceMonitor.Configuration = PerformanceMonitor.Configuration()
    )
}

public struct SystemHealthReport: Sendable {
    public let timestamp: Date
    public let memoryStats: CacheStats
    public let performanceMetrics: PerformanceMonitor.UnifiedMetrics
    public let activeAlerts: [PerformanceMonitor.PerformanceAlert]
    public let overallHealth: SystemHealth

    public var summary: String
}

public enum SystemHealth: String, Sendable {
    case excellent = "Excellent"
    case good = "Good"
    case fair = "Fair"
    case poor = "Poor"
    case critical = "Critical"

    public var description: String
    public var color: String
}

let manager = MemoryManager.shared

public struct Configuration: Sendable {
    public let maxCacheSize: Int              // Maximum number of entries
    public let maxMemoryBudget: Int           // Maximum memory in bytes
    public let cleanupInterval: TimeInterval  // Automatic cleanup interval
    public let pressureThreshold: Double      // Memory pressure threshold (0.0-1.0)
    public let enableMetrics: Bool            // Enable metrics collection
    public let enableLeakDetection: Bool      // Enable leak detection
    public let logger: any MemoryKitLogger    // Logger instance

    public init(
        maxCacheSize: Int = 1000,
        maxMemoryBudget: Int = 100 * 1024 * 1024, // 100MB
        cleanupInterval: TimeInterval = 600.0,    // 10 minutes
        pressureThreshold: Double = 0.8,
        enableMetrics: Bool = true,
        enableLeakDetection: Bool = true,
        logger: any MemoryKitLogger = MemoryKitLoggerFactory.defaultLogger()
    )
}

public struct MemoryMetrics: Sendable {
    public private(set) var cacheHits: Int
    public private(set) var cacheMisses: Int
    public private(set) var cacheEvictions: Int
    public private(set) var bytesWritten: Int
    public private(set) var bytesRead: Int
    public private(set) var cleanupOperations: Int
    public private(set) var aggressiveCleanups: Int
    public private(set) var lastCleanupTime: Date?

    public var hitRate: Double
    public var efficiency: Double
}

public struct CacheStats: Sendable {
    public let entryCount: Int
    public let totalSize: Int
    public let hitRate: Double
    public let averageAge: TimeInterval
    public let memoryPressure: Double

    public var description: String
}

public struct Configuration: Sendable {
    public let maxSize: Int                    // Maximum entries
    public let maxMemoryUsage: Int             // Maximum memory bytes
    public let defaultTTL: TimeInterval        // Default time-to-live
    public let enableTTL: Bool                 // Enable TTL tracking
    public let evictionPolicy: EvictionPolicy  // Eviction strategy
    public let compressionEnabled: Bool        // Enable compression
    public let enableMetrics: Bool             // Enable metrics

    public init(
        maxSize: Int = 1000,
        maxMemoryUsage: Int = 50 * 1024 * 1024, // 50MB
        defaultTTL: TimeInterval = 300,
        enableTTL: Bool = true,
        evictionPolicy: EvictionPolicy = .lru,
        compressionEnabled: Bool = true,
        enableMetrics: Bool = true
    )
}

public enum EvictionPolicy: Sendable {
    case lru      // Least Recently Used
    case lfu      // Least Frequently Used
    case fifo     // First In, First Out
    case random   // Random eviction
    case ttl      // Time To Live based
    case adaptive // Adaptive based on access patterns
}

public struct CacheMetrics: Sendable {
    public private(set) var hits: Int
    public private(set) var misses: Int
    public private(set) var writes: Int
    public private(set) var evictions: Int
    public private(set) var expirations: Int
    public private(set) var bytesStored: Int
    public private(set) var bytesEvicted: Int

    public var hitRate: Double
    public var evictionRate: Double
}

public struct Configuration: Sendable {
    public let maxSize: Int
    public let ttl: TimeInterval
    public let evictionPolicy: EvictionPolicy
    public let enableStatistics: Bool

    public init(
        maxSize: Int = 1000,
        ttl: TimeInterval = 300.0,
        evictionPolicy: EvictionPolicy = .leastRecentlyUsed,
        enableStatistics: Bool = true
    )
}

public enum EvictionPolicy: Sendable {
    case leastRecentlyUsed
    case leastFrequentlyUsed
    case timeToLive
    case fifo
}

public struct CacheStatistics: Sendable {
    public var hits: Int
    public var misses: Int
    public var writes: Int
    public var evictions: Int
    public var expiries: Int
    public var cleanups: Int
    public var currentSize: Int
    public var maxSize: Int

    public var hitRate: Double
    public var hitCount: Int
    public var accessCount: Int
}

public struct Configuration: Sendable {
    public let l1MaxSize: Int          // L1 max entries
    public let l1MaxMemory: Int        // L1 max memory (bytes)
    public let l2MaxSize: Int          // L2 max entries
    public let l2MaxMemory: Int        // L2 max memory (bytes)
    public let l3MaxSize: Int          // L3 max entries
    public let l3CacheDirectory: URL?  // L3 disk location
    public let defaultTTL: TimeInterval // Default TTL
    public let enableCompression: Bool  // Enable compression
    public let enableMetrics: Bool      // Enable metrics
    public let cacheIdentifier: String? // Cloud name for consistent caching

    public init(
        l1MaxSize: Int = 1000,
        l1MaxMemory: Int = 20 * 1024 * 1024,   // 20 MB for L1
        l2MaxSize: Int = 5000,
        l2MaxMemory: Int = 50 * 1024 * 1024,   // 50 MB for L2
        l3MaxSize: Int = 50000,                 // 50k entries on disk
        l3CacheDirectory: URL? = nil,
        defaultTTL: TimeInterval = 300.0,       // 5 minutes
        enableCompression: Bool = true,
        enableMetrics: Bool = true,
        cacheIdentifier: String? = nil          // Optional cloud name
    )
}

// Create cache with cloud-specific isolation
let config = MultiLevelCacheManager<String, Data>.Configuration(
    l3CacheDirectory: nil, // Uses default ~/.config/substation/multi-level-cache/
    cacheIdentifier: "production" // Cloud name
)
// Cache files stored in: ~/.config/substation/multi-level-cache/production/

/// Clean up cache files older than 8 hours for a specific cloud
@discardableResult
public static func cleanupStaleCacheFiles(
    maxAge: TimeInterval = 8 * 60 * 60,  // 8 hours default
    cloudName: String? = nil,             // Optional cloud name
    cacheDirectory: URL? = nil            // Optional custom directory
) -> Int  // Returns number of files removed

// At application startup, clean up stale cache for the current cloud
let removedCount = MultiLevelCacheManager<String, Data>.cleanupStaleCacheFiles(
    cloudName: "production"
)
if removedCount > 0 {
    print("Cleaned up \(removedCount) stale cache files")
}

public enum CachePriority: Int, CaseIterable, Sendable {
    case critical = 4  // Auth tokens, service endpoints
    case high = 3      // Active servers, current projects
    case normal = 2    // General resources
    case low = 1       // Historical data, rarely accessed

    public var weight: Double
    public var ttlMultiplier: Double
}

public struct MultiLevelCacheStatistics: Sendable {
    public let l1Stats: CacheTierStatistics
    public let l2Stats: CacheTierStatistics
    public let l3Stats: CacheTierStatistics
    public let overallHitRate: Double
    public let totalMisses: Int
    public let compressionStats: CompressionStats

    public var description: String
}

public struct CacheTierStatistics: Sendable {
    public let entries: Int
    public let maxEntries: Int
    public let memoryUsage: Int
    public let maxMemory: Int
    public let hitCount: Int
    public let hitRate: Double
}

public struct CompressionStats: Sendable {
    public var totalCompressions: Int
    public var totalOriginalBytes: Int
    public var totalCompressedBytes: Int
    public var averageCompressionTime: TimeInterval
    public var averageDecompressionTime: TimeInterval

    public var averageCompressionRatio: Double
}

public enum MultiLevelCacheError: Error, LocalizedError {
    case compressionFailed
    case decompressionFailed

    public var errorDescription: String?
    public var failureReason: String?
    public var recoverySuggestion: String?
}

public struct Configuration: Sendable {
    public let maxPoolSize: Int           // Maximum pool size
    public let minPoolSize: Int           // Minimum pool size
    public let idleTimeout: TimeInterval  // Idle resource timeout
    public let enableMetrics: Bool        // Enable metrics

    public init(
        maxPoolSize: Int = 10,
        minPoolSize: Int = 2,
        idleTimeout: TimeInterval = 300,
        enableMetrics: Bool = true
    )
}

public init(
    configuration: Configuration = Configuration(),
    factory: @escaping @Sendable () async throws -> Resource,
    cleanup: @escaping @Sendable (Resource) async -> Void = { _ in },
    validator: @escaping @Sendable (Resource) async -> Bool = { _ in true }
)

public struct PoolMetrics: Sendable {
    public private(set) var acquisitionsFromPool: Int
    public private(set) var acquisitionsCreated: Int
    public private(set) var releasesToPool: Int
    public private(set) var releasesDiscarded: Int
    public private(set) var validationFailures: Int
    public private(set) var idleCleanups: Int
    public private(set) var preCreations: Int

    public var poolHitRate: Double
}

public struct PoolStats: Sendable {
    public let availableCount: Int
    public let inUseCount: Int
    public let maxPoolSize: Int
    public let metrics: PoolMetrics

    public var utilization: Double
    public var description: String
}

public struct Configuration: Sendable {
    public let enableMonitoring: Bool
    public let metricsCollectionInterval: TimeInterval
    public let alertThresholds: AlertThresholds

    public init(
        enableMonitoring: Bool = true,
        metricsCollectionInterval: TimeInterval = 300.0,
        alertThresholds: AlertThresholds = AlertThresholds()
    )
}

public struct AlertThresholds: Sendable {
    public let memoryUsageThreshold: Double
    public let cacheHitRateThreshold: Double
    public let responseTimeThreshold: TimeInterval

    public init(
        memoryUsageThreshold: Double = 0.8,
        cacheHitRateThreshold: Double = 0.7,
        responseTimeThreshold: TimeInterval = 2.0
    )
}

public enum PerformanceAlert: Sendable {
    case highMemoryUsage(current: Double, threshold: Double)
    case lowCacheHitRate(current: Double, threshold: Double)
    case slowResponseTime(current: TimeInterval, threshold: TimeInterval)

    public var severity: AlertSeverity
    public var description: String
}

public enum AlertSeverity: String, Sendable {
    case info = "INFO"
    case warning = "WARNING"
    case critical = "CRITICAL"
}

public struct UnifiedMetrics: Sendable {
    public let timestamp: Date
    public let memoryMetrics: MemoryMetrics
    public let cacheMetrics: CacheMetrics
    public let systemMetrics: SystemMetrics
    public let performanceProfile: PerformanceProfile

    public var summary: String
}

public struct SystemMetrics: Sendable {
    public let memoryUsage: Double
    public let cpuUsage: Double
    public let timestamp: Date
}

public struct PerformanceProfile: Sendable {
    public let averageResponseTime: TimeInterval
    public let cacheEfficiency: Double
    public let systemLoad: Double

    public var grade: PerformanceGrade
}

public enum PerformanceGrade: String, Sendable {
    case excellent = "A+"
    case good = "A"
    case fair = "B"
    case poor = "C"
    case critical = "F"

    public var description: String
}

public init(logger: any MemoryKitLogger, enablePeriodicReporting: Bool = false)

public struct ComprehensiveMetrics: Sendable {
    public let timestamp: Date
    public let cacheManagers: [String: CacheMetrics]
    public let typedCacheManagers: [String: CacheStatistics]

    public var overallStats: OverallCacheStats
}

public struct OverallCacheStats: Sendable {
    public let totalEntries: Int
    public let totalSize: Int
    public let hitRate: Double

    public var description: String
}

public protocol CacheManagerProtocol: Actor {
    func getMetrics() async -> CacheMetrics
}

public protocol TypedCacheManagerProtocol: Actor {
    func getStatistics() async -> CacheStatistics
}

public protocol MemoryKitLogger: Sendable {
    func logDebug(_ message: String, context: [String: Any])
    func logInfo(_ message: String, context: [String: Any])
    func logWarning(_ message: String, context: [String: Any])
    func logError(_ message: String, context: [String: Any])
}

public struct DefaultMemoryKitLogger: MemoryKitLogger {
    public init(prefix: String = "[MemoryKit]")
    public init(prefix: String = "[MemoryKit]", logToFile: Bool)
    public init(prefix: String = "[MemoryKit]", logFileURL: URL)
    public init(prefix: String = "[MemoryKit]", logFilePath: String)
}

public struct SilentMemoryKitLogger: MemoryKitLogger {
    public init()
}

public enum MemoryKitLoggerFactory {
    public static func fileLogger(logFilePath: String, prefix: String = "[MemoryKit]") -> any MemoryKitLogger
    public static func fileLogger(logFileURL: URL, prefix: String = "[MemoryKit]") -> any MemoryKitLogger
    public static func consoleLogger(prefix: String = "[MemoryKit]") -> any MemoryKitLogger
    public static func silentLogger() -> any MemoryKitLogger
    public static func defaultLogger() -> any MemoryKitLogger  // Returns SilentMemoryKitLogger
}

// Store and retrieve simple data
let memoryManager = MemoryManager.shared
await memoryManager.start()

// Store data
await memoryManager.store("Hello, World!", forKey: "greeting")
await memoryManager.store(userData, forKey: "user_123")

// Retrieve data
if let greeting = await memoryManager.retrieve(forKey: "greeting", as: String.self) {
    print(greeting) // "Hello, World!"
}

// Check cache stats
let stats = await memoryManager.getCacheStats()
print("Cache hit rate: \(stats.hitRate * 100)%")

// Create a typed cache for specific data types
let userCache = TypedCacheManager<String, User>(
    configuration: TypedCacheManager<String, User>.Configuration(
        maxSize: 1000,
        ttl: 300,
        evictionPolicy: .leastRecentlyUsed
    )
)

// Store user data
let user = User(id: "123", name: "John Doe")
await userCache.store(user, forKey: "user_123")

// Retrieve user data
if let cachedUser = await userCache.retrieve(forKey: "user_123") {
    print("Found user: \(cachedUser.name)")
}

// Get statistics
let stats = await userCache.getStatistics()
print("Hit rate: \(stats.hitRate * 100)%")

// Create a cache with custom eviction policy
let cache = CacheManager<String, Server>(
    configuration: CacheManager<String, Server>.Configuration(
        maxSize: 500,
        defaultTTL: 600,
        evictionPolicy: .adaptive
    )
)
await cache.start()

// Store with custom TTL
await cache.set(server, forKey: "server_123", ttl: 1800)

// Retrieve
if let cached = await cache.get("server_123") {
    print("Server: \(cached.name)")
}

// Check metrics
let metrics = await cache.getMetrics()
print("Eviction rate: \(metrics.evictionRate * 100)%")

// Create multi-level cache for OpenStack resources
let resourceCache = MultiLevelCacheManager<String, Server>(
    configuration: MultiLevelCacheManager<String, Server>.Configuration(
        l1MaxSize: 100,      // Keep 100 hot items in memory
        l2MaxSize: 500,      // Keep 500 compressed items
        l3MaxSize: 10000,    // Keep 10k items on disk
        defaultTTL: 3600     // 1 hour TTL
    )
)
await resourceCache.start()

// Store server with priority
let server = Server(id: "srv-123", name: "production-web-01")
await resourceCache.store(
    server,
    forKey: server.id,
    priority: .high,     // High priority for production servers
    customTTL: 7200      // 2 hour TTL
)

// Retrieve (automatically promotes between levels)
if let cachedServer = await resourceCache.retrieve(
    forKey: "srv-123",
    as: Server.self
) {
    print("Server: \(cachedServer.name)")
}

// Get statistics
let stats = await resourceCache.getStatistics()
print(stats.description)

// Create a pool for expensive database connections
let dbPool = ResourcePool<DatabaseConnection>(
    configuration: ResourcePool<DatabaseConnection>.Configuration(
        maxPoolSize: 10,
        minPoolSize: 2,
        idleTimeout: 300
    ),
    factory: {
        // Create new connection
        return try await DatabaseConnection.create()
    },
    cleanup: { connection in
        // Clean up connection
        await connection.close()
    },
    validator: { connection in
        // Validate connection is still alive
        return await connection.isAlive()
    }
)
await dbPool.start()

// Use pooled resource
let connection = try await dbPool.acquire()
defer {
    Task {
        await dbPool.release(connection)
    }
}
// Use connection...

// Create a file logger for debugging
let fileLogger = MemoryKitLoggerFactory.fileLogger(
    logFilePath: "/var/log/memorykit.log",
    prefix: "[MyApp]"
)

let memoryManager = MemoryManager(configuration: MemoryManager.Configuration(
    maxCacheSize: 5000,
    logger: fileLogger
))

// Or use console logging
let consoleLogger = MemoryKitLoggerFactory.consoleLogger(prefix: "[Debug]")

// For production, use silent logger (default)
let silentLogger = MemoryKitLoggerFactory.silentLogger()

let config = MemoryManager.Configuration(
    maxCacheSize: 5000,              // Entries before eviction
    maxMemoryBudget: 150_000_000,    // 150MB budget
    cleanupInterval: 600.0,          // Clean every 10 minutes
    pressureThreshold: 0.8,          // Trigger at 80% usage
    enableMetrics: true,             // Track performance
    enableLeakDetection: true,       // Detect memory leaks
    logger: CustomLogger()           // Custom logging
)

// For read-heavy workloads
let readOptimized = MultiLevelCacheManager.Configuration(
    l1MaxSize: 2000,      // Large L1 for fast reads
    l1MaxMemory: 50_000_000,
    l2MaxSize: 10000,     // Large L2 backup
    l2MaxMemory: 100_000_000,
    l3MaxSize: 100000     // Massive L3 for historical data
)

// For write-heavy workloads
let writeOptimized = MultiLevelCacheManager.Configuration(
    l1MaxSize: 500,       // Small L1 to reduce write pressure
    l1MaxMemory: 10_000_000,
    l2MaxSize: 2000,      // Medium L2
    l2MaxMemory: 30_000_000,
    l3MaxSize: 50000,     // Large L3 for persistence
    enableCompression: true // Compress to reduce I/O
)

// Critical, frequently accessed data -> L1
await cache.store(authToken, forKey: "auth", priority: .critical)

// Important but less frequent -> L2
await cache.store(userProfile, forKey: "user", priority: .high)

// Historical or archival -> L3
await cache.store(auditLog, forKey: "audit", priority: .low)

// Short TTL for volatile data
await cache.set(marketPrice, forKey: "price", ttl: 60) // 1 minute

// Medium TTL for semi-static data
await cache.set(userSession, forKey: "session", ttl: 3600) // 1 hour

// Long TTL for stable data
await cache.set(configuration, forKey: "config", ttl: 86400) // 1 day

// Regular health checks
let health = await memoryKit.getHealthReport()
if health.overallHealth == .poor {
    await memoryKit.forceCleanup()
}

// Track cache efficiency
let stats = await cache.getMetrics()
if stats.hitRate < 0.7 {
    // Consider adjusting cache size or TTL
}

// Check memory pressure
if await memoryManager.isUnderMemoryPressure() {
    // Reduce cache usage or force cleanup
    await memoryManager.forceCleanup()
}

// Pool expensive resources instead of creating new ones
let pool = ResourcePool<ExpensiveResource>(
    configuration: ResourcePool.Configuration(
        maxPoolSize: 20,
        minPoolSize: 5
    ),
    factory: { try await ExpensiveResource.create() }
)

class TUI {
    var cachedServers: [Server] = []

    func refreshServers() {
        cachedServers = fetchServers()
    }
}

class TUI {
    let cache = MemoryManager.shared

    func refreshServers() async {
        let servers = await fetchServers()
        await cache.store(servers, forKey: "servers")
    }

    func getServers() async -> [Server] {
        return await cache.retrieve(forKey: "servers", as: [Server].self) ?? []
    }
}

var cache: [String: Any] = [:]
cache["user_123"] = user

let cache = TypedCacheManager<String, User>(
    configuration: TypedCacheManager.Configuration()
)
await cache.store(user, forKey: "user_123")

// Check current usage
let stats = await memoryManager.getCacheStats()
print("Memory pressure: \(stats.memoryPressure * 100)%")

// Force cleanup if needed
if stats.memoryPressure > 0.9 {
    await memoryManager.forceCleanup()
}

// Analyze cache metrics
let metrics = await cache.getMetrics()
print("Hit rate: \(metrics.hitRate)")
print("Eviction rate: \(metrics.evictionRate)")

// Adjust configuration
// Increase cache size or TTL if eviction rate is high

// Enable detailed logging
let logger = MemoryKitLoggerFactory.fileLogger(
    logFilePath: "/tmp/memorykit-debug.log",
    prefix: "[Debug]"
)
let cache = CacheManager<String, MyType>(
    configuration: CacheManager.Configuration(),
    logger: logger
)

// Handle compression errors gracefully
do {
    let value = await multiLevelCache.retrieve(forKey: "key", as: MyType.self)
} catch MultiLevelCacheError.decompressionFailed {
    // Entry was corrupted, it will be removed automatically
    // Fetch fresh data
}

// Safe to call from any thread/task
Task {
    await cache.set(data1, forKey: "key1")
}
Task {
    await cache.set(data2, forKey: "key2")
}
// No race conditions or data corruption

// Safe retrieval with fallback
let data = await cache.retrieve(forKey: "key", as: MyType.self) ?? defaultValue

// Resource pool with error handling
do {
    let resource = try await pool.acquire()
    // Use resource
    await pool.release(resource)
} catch {
    print("Failed to acquire resource: \(error)")
}