Configuration

struct Configuration

Configuration options for the memory cache behavior and limits.

  • Whether to enable thread synchronization using DispatchSemaphore (default: true) When true: All cache operations are synchronized for thread safety When false: No synchronization, caller must ensure thread safety

    Declaration

    Swift

    public let enableThreadSynchronization: Bool

  • Memory and capacity constraints for the cache.

    Declaration

    Swift

    public let memoryUsageLimitation: MemoryUsageLimitation

  • Default TTL for non-null elements (in seconds).

    Declaration

    Swift

    public let defaultTTL: TimeInterval

  • Default TTL for null elements (in seconds).

    Declaration

    Swift

    public let defaultTTLForNullElement: TimeInterval

  • Randomization range for TTL elements to prevent cache stampede (in seconds).

    Declaration

    Swift

    public let ttlRandomizationRange: TimeInterval

  • Key validation function that returns true for valid keys. Fixed at initialization.

    Declaration

    Swift

    public let keyValidator: (Key) -> Bool

  • Function to calculate memory cost of elements in bytes.

    This closure is called for each element to determine its memory footprint for eviction decisions. The returned element should represent the actual memory usage in bytes.

    Usage Guidelines:

    • For reference types (classes): Return the actual memory size (e.g., image data size, buffer length)
    • For element types: Can return 0 as memory layout is automatically calculated by the system
    • For complex objects: Sum up all contained data sizes (strings, arrays, etc.)
    • For nil elements: Return 0 (handled automatically by the cache)

    Examples:

    // For UIImage: return actual image data size
costProvider: { image in
    guard let cgImage = image.cgImage else { return 0 }
    return cgImage.bytesPerRow * cgImage.height
}

// For String: return character count (approximate)
costProvider: { $0.count * 2 }

// For Data: return actual byte count
costProvider: { $0.count }

// For complex objects: sum up all data
costProvider: { obj in
    return obj.stringData.count + obj.binaryData.count + obj.metadata.count
}

    Important Notes:

    • Cost Unit: The returned value represents memory cost in bytes
    • The returned element should be positive and reasonable (avoid extremely large elements)
    • Should be consistent for the same input (deterministic)
    • Performance: This closure is called frequently during eviction, so keep it fast
    • Memory limit: Total cost across all elements should not exceed MemoryUsageLimitation.memory
    • Default behavior: Returns 0 if not specified, relying on automatic memory layout calculation

    Declaration

    Swift

    public let costProvider: (Element) -> Int

  • Creates a new configuration with specified parameters.

    Declaration

    Swift

    public init(
    enableThreadSynchronization: Bool = true,
    memoryUsageLimitation: MemoryUsageLimitation = .init(),
    defaultTTL: TimeInterval = .infinity,
    defaultTTLForNullElement: TimeInterval = .infinity,
    ttlRandomizationRange: TimeInterval = 0,
    keyValidator: @escaping (Key) -> Bool = { _ in true },
    costProvider: @escaping (Element) -> Int = { _ in 0 }
)

    Parameters

    enableThreadSynchronization

    Enable DispatchSemaphore synchronization for thread safety (default: true)
    memoryUsageLimitation

    Memory and capacity constraints (default: unlimited)
    defaultTTL

    Default TTL for non-nil elements (default: .infinity)
    defaultTTLForNullElement

    Default TTL for nil elements (default: .infinity)
    ttlRandomizationRange

    TTL randomization range (default: 0)
    keyValidator

    Key validation closure (default: always true)
    costProvider

    Memory cost calculation closure that returns cost in bytes. Should return actual memory usage for accurate eviction decisions (default: returns 0)

  • Default configuration (thread-synchronized with DispatchSemaphore, unlimited size, no expiration, all keys valid)

    Declaration

    Swift

    public static var defaultConfig: Configuration { get }