CacheStorage (2/3)

BlueprintUI/Sources/CrossLayoutCaching/Cache/CacheImplementations/EnvironmentAndValueValidatingCache.swift

@@ -0,0 +1,90 @@
+import Foundation
+
+/// A convenience wrapper around ValidatingCache which ensures that only values which were cached in equivalent environments are returned, and allows for additional data to be stored to be validated.
+@_spi(HostingViewContext) public final class EnvironmentAndValueValidatingCache<Key, Value, AdditionalValidationData>: Sendable where Key: Hashable & Sendable {
+
+    private var backing = ValidatingCache<Key, Value, (EnvironmentAccessList, AdditionalValidationData)>()
+
+    public init() {}
+
+    /// Retrieves or creates a value based on a key and a validation function, alongside environment validation.
+    /// - Parameters:
+    ///   - key: The key to look up.
+    ///   - environment: The current environment. A frozen version of this environment will be preserved along with freshly cached values for comparison.
+    ///   - context: The equivalency context in which the environment should be evaluated.
+    ///   - validate: A function that evaluates whether or not a given result is still valid.
+    ///   - create: Creates a fresh cache entry no valid cached data is available, and stores it.
+    /// - Returns: Either a cached or newly created value.
+    /// - Note: Generally, prefer the `validationValue` versions of this method if the validation value conforms to ContextuallyEquivalent or Equatable.
+    func retrieveOrCreate(
+        key: Key,
+        environment: Environment,
+        context: CrossLayoutCacheableContext,
+        validate: (AdditionalValidationData) -> Bool,
+        create: (Environment) -> (Value, AdditionalValidationData)
+    ) -> Value {
+        backing.retrieveOrCreate(key: key) {
+            environment.isCacheablyEquivalent(to: $0.0, in: context) && validate($0.1)
+        } create: {
+            let ((value, additional), accessList) = environment.observingAccess { environment in
+                create(environment)
+            }
+            return (value, (accessList, additional))
+        }
+    }
+
+}
+
+@_spi(HostingViewContext) extension EnvironmentAndValueValidatingCache where AdditionalValidationData: CrossLayoutCacheable {
+
+    /// Retrieves or creates a value based on a key and a validation value, alongside environment validation.
+    /// - Parameters:
+    ///   - key: The key to look up.
+    ///   - environment: The current environment. A frozen version of this environment will be preserved along with freshly cached values for comparison.
+    ///   - context: The equivalency context in which the environment and validation values should be evaluated.
+    ///   - validationValue: A value that will be compared using contextual equivalence that evaluates whether or not a given result is still valid.
+    ///   - create: Creates a fresh cache entry no valid cached data is available, and stores it.
+    /// - Returns: Either a cached or newly created value.
+    public func retrieveOrCreate(
+        key: Key,
+        environment: Environment,
+        validationValue: AdditionalValidationData,
+        context: CrossLayoutCacheableContext,
+        create: (Environment) -> (Value)
+    ) -> Value {
+        retrieveOrCreate(key: key, environment: environment, context: context) {
+            $0.isCacheablyEquivalent(to: validationValue, in: context)
+        } create: {
+            (create($0), validationValue)
+        }
+
+    }
+
+}
+
+@_spi(HostingViewContext) extension EnvironmentAndValueValidatingCache where AdditionalValidationData: Equatable {
+
+    /// Retrieves or creates a value based on a key and a validation value, alongside environment validation.
+    /// - Parameters:
+    ///   - key: The key to look up.
+    ///   - environment: The current environment. A frozen version of this environment will be preserved along with freshly cached values for comparison.
+    ///   - context: The equivalency context in which the environment should be evaluated.
+    ///   - validationValue: A value that will be compared using strict equality that evaluates whether or not a given result is still valid.
+    ///   - create: Creates a fresh cache entry no valid cached data is available, and stores it.
+    /// - Returns: Either a cached or newly created value.
+    @_disfavoredOverload public func retrieveOrCreate(
+        key: Key,
+        environment: Environment,
+        validationValue: AdditionalValidationData,
+        context: CrossLayoutCacheableContext,
+        create: (Environment) -> (Value)
+    ) -> Value {
+        retrieveOrCreate(key: key, environment: environment, context: context) {
+            $0 == validationValue
+        } create: {
+            (create($0), validationValue)
+        }
+    }
+
+}
+

BlueprintUI/Sources/CrossLayoutCaching/Cache/CacheImplementations/EnvironmentValidatingCache.swift

@@ -0,0 +1,33 @@
+import Foundation
+
+/// A convenience wrapper around ValidatingCache which ensures that only values which were cached in equivalent environments are returned.
+@_spi(HostingViewContext) public final class EnvironmentValidatingCache<Key, Value>: Sendable where Key: Hashable & Sendable {
+
+    private var backing = ValidatingCache<Key, Value, EnvironmentAccessList>()
+
+    public init() {}
+
+    /// Retrieves or creates a value based on a key and environment validation.
+    /// - Parameters:
+    ///   - key: The key to look up.
+    ///   - environment: The current environment. A frozen version of this environment will be preserved along with freshly cached values for comparison.
+    ///   - context: The equivalency context in which the environment should be evaluated.
+    ///   - create: Creates a fresh cache entry no valid cached data is available, and stores it.
+    /// - Returns: Either a cached or newly created value.
+    func retrieveOrCreate(
+        key: Key,
+        environment: Environment,
+        context: CrossLayoutCacheableContext,
+        create: (Environment) -> Value
+    ) -> Value {
+        backing.retrieveOrCreate(key: key) {
+            environment.isCacheablyEquivalent(to: $0, in: context)
+        } create: {
+            environment.observingAccess { environment in
+                create(environment)
+            }
+        }
+    }
+
+}
+

BlueprintUI/Sources/CrossLayoutCaching/Cache/CacheImplementations/ValidatingCache.swift

@@ -0,0 +1,77 @@
+import Foundation
+
+/// Validating cache is a cache which, if it has a value for a key, runs a closure to verify that the cache value is still relevant and not state.
+/// This is useful for cases when you might otherwise wish to store the validation data as a key, but it does not conform to Hashable, or its hashability properties do not neccessarily affect the validity of the cached data.
+@_spi(HostingViewContext) public final class ValidatingCache<Key, Value, ValidationData>: Sendable where Key: Hashable & Sendable {
+
+    private var storage: [Key: ValueStorage] = [:]
+
+    private struct ValueStorage {
+        let value: Value
+        let validationData: ValidationData
+    }
+
+    public init() {}
+
+    /// Retrieves the value for a given key, without evaluating any validation conditions.
+    public subscript(uncheckedKey key: Key) -> Value? {
+        storage[key]?.value
+    }
+
+    /// Retrieves or creates a value based on a key and validation function.
+    /// - Parameters:
+    ///   - key: The key to look up.
+    ///   - validate: A function that evaluates whether or not a given result is still valid.
+    ///   - create: Creates a fresh cache entry no valid cached data is available, and stores it.
+    /// - Returns: Either a cached or newly created value.
+    public func retrieveOrCreate(
+        key: Key,
+        validate: (ValidationData) -> Bool,
+        create: () -> (Value, ValidationData)
+    ) -> Value {
+        if let valueStorage = storage[key] {
+            Logger.logValidatingCrossLayoutCacheKeyHit(key: key)
+            let validationToken = Logger.logValidatingCacheValidationStart(key: key)
+            if validate(valueStorage.validationData) {
+                Logger.logValidatingCacheHitAndValidationSuccess(key: key)
+                Logger.logValidatingCacheValidationEnd(validationToken, key: key)
+                return valueStorage.value
+                #if DEBUG
+                // FIXME: WAY TO MAKE SURE THIS DOESN'T SHIP ON.
+                // Enable this to always evaluate the create block to assert that the caching is producing the expected value.
+                //                if let stored = valueStorage.value as? (any Equatable) {
+                //                    let fresh = create().0 as! Equatable
+                //                    assert(stored.isEqual(fresh))
+                //                }
+                // return valueStorage.value
+                #endif
+            } else {
+                Logger.logValidatingCacheHitAndValidationFailure(key: key)
+                Logger.logValidatingCacheValidationEnd(validationToken, key: key)
+            }
+        } else {
+            Logger.logValidatingCrossLayoutCacheKeyMiss(key: key)
+        }
+        let createToken = Logger.logValidatingCacheFreshValueCreationStart(key: key)
+        let (fresh, validationData) = create()
+        Logger.logValidatingCacheFreshValueCreationEnd(createToken, key: key)
+        storage[key] = ValueStorage(value: fresh, validationData: validationData)
+        return fresh
+    }
+
+    public func removeValue(forKey key: Key) -> Value? {
+        storage.removeValue(forKey: key)?.value
+    }
+
+}
+
+extension Equatable {
+
+    fileprivate func isEqual(_ other: any Equatable) -> Bool {
+        guard let other = other as? Self else {
+            return false
+        }
+        return self == other
+    }
+
+}

BlueprintUI/Sources/CrossLayoutCaching/Cache/CacheKey.swift

@@ -0,0 +1,27 @@
+import Foundation
+
+/// Types conforming to this protocol can be used as keys in `HostingViewContext`.
+///
+/// Using a type as the key allows us to strongly type each value, with the
+/// key's `CrossLayoutCacheKey.Value` associated value.
+///
+/// ## Example
+///
+/// Usually a key is implemented with an uninhabited type, such an empty enum.
+///
+///     enum WidgetCountsKey: CrossLayoutCacheKey {
+///         static let emptyValue: [WidgetID: Int] = [:]
+///     }
+///
+/// You can write a small extension on `HostingViewContext` to make it easier to use your key.
+///
+///     extension HostingViewContext {
+///         var widgetCounts: [WidgetID: Int] {
+///             get { self[WidgetCountsKey.self] }
+///             set { self[WidgetCountsKey.self] = newValue }
+///         }
+///     }
+public protocol CrossLayoutCacheKey {
+    associatedtype Value
+    static var emptyValue: Self.Value { get }
+}

BlueprintUI/Sources/CrossLayoutCaching/Cache/HostingViewContext.swift

@@ -0,0 +1,85 @@
+import Foundation
+import UIKit
+
+/// Environment-associated storage used to cache types used across layout passes (eg, size calculations).
+/// The storage itself is type-agnostic, requiring only that its keys and values conform to the `CrossLayoutCacheKey` protocol
+/// Caches are responsible for managing their own lifetimes and eviction strategies.
+@_spi(HostingViewContext) public final class HostingViewContext: Sendable, CustomDebugStringConvertible {
+
+    // Optional name to distinguish between instances for debugging purposes.
+    public var name: String? = nil
+    fileprivate var storage: [ObjectIdentifier: Any] = [:]
+
+    init() {
+        NotificationCenter.default.addObserver(
+            forName: UIApplication.didReceiveMemoryWarningNotification,
+            object: nil,
+            queue: .main
+        ) { [weak self] _ in
+            self?.storage.removeAll()
+        }
+    }
+
+    public subscript<KeyType>(key: KeyType.Type) -> KeyType.Value where KeyType: CrossLayoutCacheKey {
+        get {
+            storage[ObjectIdentifier(key), default: KeyType.emptyValue] as! KeyType.Value
+        }
+        set {
+            storage[ObjectIdentifier(key)] = newValue
+        }
+    }
+
+    public var debugDescription: String {
+        let debugName = if let name {
+            "HostingViewContext (\(name))"
+        } else {
+            "HostingViewContext"
+        }
+        return "\(debugName): \(storage.count) entries"
+    }
+
+}
+
+extension Environment {
+
+    struct HostingViewContextKey: InternalEnvironmentKey {
+        static var defaultValue = HostingViewContext()
+    }
+
+
+    @_spi(HostingViewContext) public var hostingViewContext: HostingViewContext {
+        get { self[HostingViewContextKey.self] }
+        set { self[HostingViewContextKey.self] = newValue }
+    }
+
+}
+
+/// A UUID that changes based on value changes of the containing type.
+/// Two fingerprinted objects may be quickly compared for equality by comparing their fingerprints.
+/// This is roughly analagous to a hash, although with inverted properties: Two objects with the same fingerprint can be trivially considered equal, but two otherwise equal objects may have different fingerprint.
+/// - Note: This type is deliberately NOT equatable – this is to prevent accidental inclusion of it when its containing type is equatable.
+struct CacheComparisonFingerprint: CrossLayoutCacheable, CustomStringConvertible {
+
+    typealias Value = UUID
+
+    var value: Value
+
+    init() {
+        value = Value()
+    }
+
+    mutating func modified() {
+        value = Value()
+    }
+
+    /// - Note: This is a duplicate message but: this type is deliberately NOT equatable – this is to prevent accidental inclusion of it when its containing type is equatable. Use this instead.
+    func isCacheablyEquivalent(to other: CacheComparisonFingerprint?, in context: CrossLayoutCacheableContext) -> Bool {
+        value == other?.value
+    }
+
+    var description: String {
+        value.uuidString
+    }
+
+}
+