Swiftswiftioscachingasync-awaitproduction-ready
Async Image Cache with LRU
Actor-based async image downloading and caching system using URLSession, NSCache with LRU eviction, disk persistence, and memory pressure handling for iOS apps.
import UIKit
/// Thread-safe async image cache with memory + disk layers
actor ImageCache {
static let shared = ImageCache()
private let memoryCache = NSCache<NSString, UIImage>()
private let fileManager = FileManager.default
private let cacheDirectory: URL
private var activeTasks: [URL: Task<UIImage?, Never>] = [:]
// Configuration
private let maxMemoryCost: Int // bytes
private let maxDiskSize: Int // bytes
private let diskTTL: TimeInterval // seconds
init(
maxMemoryMB: Int = 100,
maxDiskMB: Int = 500,
diskTTLHours: Int = 72
) {
self.maxMemoryCost = maxMemoryMB * 1024 * 1024
self.maxDiskSize = maxDiskMB * 1024 * 1024
self.diskTTL = TimeInterval(diskTTLHours * 3600)
let paths = fileManager.urls(for: .cachesDirectory, in: .userDomainMask)
self.cacheDirectory = paths[0].appendingPathComponent("ImageCache", isDirectory: true)
try? fileManager.createDirectory(at: cacheDirectory, withIntermediateDirectories: true)
memoryCache.totalCostLimit = maxMemoryCost
memoryCache.countLimit = 200
// Listen for memory warnings
Task { @MainActor in
NotificationCenter.default.addObserver(
forName: UIApplication.didReceiveMemoryWarningNotification,
object: nil,
queue: .main
) { [weak memoryCache] _ in
memoryCache?.removeAllObjects()
}
}
}
/// Fetch image from cache or download. Deduplicates concurrent requests.
func image(for url: URL, size: CGSize? = nil) async -> UIImage? {
let cacheKey = cacheKey(for: url, size: size)
// Check memory cache first
if let cached = memoryCache.object(forKey: cacheKey as NSString) {
return cached
}
// Check disk cache
if let diskImage = loadFromDisk(key: cacheKey) {
let cost = diskImage.jpegData(compressionQuality: 1.0)?.count ?? 0
memoryCache.setObject(diskImage, forKey: cacheKey as NSString, cost: cost)
return diskImage
}
// Deduplicate in-flight requests for the same URL
if let existingTask = activeTasks[url] {
return await existingTask.value
}
let task = Task<UIImage?, Never> {
guard let image = await download(url: url) else { return nil }
let finalImage: UIImage
if let size = size {
finalImage = image.resized(to: size)
} else {
finalImage = image
}
// Store in both caches
let cost = finalImage.jpegData(compressionQuality: 1.0)?.count ?? 0
memoryCache.setObject(finalImage, forKey: cacheKey as NSString, cost: cost)
saveToDisk(image: finalImage, key: cacheKey)
return finalImage
}
activeTasks[url] = task
let result = await task.value
activeTasks[url] = nil
return result
}
/// Prefetch images for upcoming content
func prefetch(urls: [URL]) {
for url in urls {
Task {
_ = await image(for: url)
}
}
}
/// Clear all caches
func clearAll() {
memoryCache.removeAllObjects()
try? fileManager.removeItem(at: cacheDirectory)
try? fileManager.createDirectory(at: cacheDirectory, withIntermediateDirectories: true)
}
/// Remove expired disk entries
func pruneExpiredEntries() {
guard let files = try? fileManager.contentsOfDirectory(
at: cacheDirectory,
includingPropertiesForKeys: [.contentModificationDateKey, .fileSizeKey]
) else { return }
let expirationDate = Date().addingTimeInterval(-diskTTL)
for fileURL in files {
guard let attributes = try? fileURL.resourceValues(forKeys: [.contentModificationDateKey]),
let modDate = attributes.contentModificationDate,
modDate < expirationDate else { continue }
try? fileManager.removeItem(at: fileURL)
}
}
// MARK: - Private Methods
private func download(url: URL) async -> UIImage? {
do {
let (data, response) = try await URLSession.shared.data(from: url)
guard let httpResponse = response as? HTTPURLResponse,
(200...299).contains(httpResponse.statusCode),
let image = UIImage(data: data) else {
return nil
}
return image
} catch {
return nil
}
}
private func cacheKey(for url: URL, size: CGSize?) -> String {
var key = url.absoluteString
if let size = size {
key += "_\(Int(size.width))x\(Int(size.height))"
}
return key.data(using: .utf8)!
.base64EncodedString()
.replacingOccurrences(of: "/", with: "_")
}
private func diskPath(for key: String) -> URL {
cacheDirectory.appendingPathComponent(key)
}
private func loadFromDisk(key: String) -> UIImage? {
let path = diskPath(for: key)
guard fileManager.fileExists(atPath: path.path),
let data = try? Data(contentsOf: path),
let image = UIImage(data: data) else {
return nil
}
// Check TTL
if let attrs = try? fileManager.attributesOfItem(atPath: path.path),
let modDate = attrs[.modificationDate] as? Date,
Date().timeIntervalSince(modDate) > diskTTL {
try? fileManager.removeItem(at: path)
return nil
}
return image
}
private func saveToDisk(image: UIImage, key: String) {
guard let data = image.jpegData(compressionQuality: 0.85) else { return }
let path = diskPath(for: key)
try? data.write(to: path, options: .atomic)
}
}
// MARK: - UIImage Extension
extension UIImage {
func resized(to targetSize: CGSize) -> UIImage {
let renderer = UIGraphicsImageRenderer(size: targetSize)
return renderer.image { _ in
self.draw(in: CGRect(origin: .zero, size: targetSize))
}
}
}title: "Async Image Cache with LRU" description: "Actor-based async image downloading and caching system using URLSession, NSCache with LRU eviction, disk persistence, and memory pressure handling for iOS apps." category: "Swift" language: "swift" tags: ["swift", "ios", "caching", "async-await", "production-ready"] createdAt: "2024-12-05" updatedAt: "2025-01-13"
Overview
An actor-based image caching system for iOS that provides thread-safe, two-tier caching (memory + disk) with async/await support. This eliminates common issues in image loading like redundant network requests, memory pressure crashes, and UI thread blocking.
Key design decisions:
- Actor isolation guarantees thread safety without manual lock management
- Request deduplication via
activeTasksdictionary prevents multiple downloads of the same image - NSCache for memory layer automatically evicts under memory pressure (LRU behavior built-in)
- Disk persistence with TTL survives app restarts while preventing unbounded growth
- Image resizing before caching reduces memory footprint for thumbnail use cases
- Memory warning handling proactively clears the memory cache to prevent termination
Code
import UIKit
actor ImageCache {
static let shared = ImageCache()
private let memoryCache = NSCache<NSString, UIImage>()
private let fileManager = FileManager.default
private let cacheDirectory: URL
private var activeTasks: [URL: Task<UIImage?, Never>] = [:]
private let maxMemoryCost: Int
private let maxDiskSize: Int
private let diskTTL: TimeInterval
init(maxMemoryMB: Int = 100, maxDiskMB: Int = 500, diskTTLHours: Int = 72) {
self.maxMemoryCost = maxMemoryMB * 1024 * 1024
self.maxDiskSize = maxDiskMB * 1024 * 1024
self.diskTTL = TimeInterval(diskTTLHours * 3600)
let paths = fileManager.urls(for: .cachesDirectory, in: .userDomainMask)
self.cacheDirectory = paths[0].appendingPathComponent("ImageCache", isDirectory: true)
try? fileManager.createDirectory(at: cacheDirectory, withIntermediateDirectories: true)
memoryCache.totalCostLimit = maxMemoryCost
memoryCache.countLimit = 200
}
func image(for url: URL, size: CGSize? = nil) async -> UIImage? {
let cacheKey = cacheKey(for: url, size: size)
if let cached = memoryCache.object(forKey: cacheKey as NSString) {
return cached
}
if let diskImage = loadFromDisk(key: cacheKey) {
let cost = diskImage.jpegData(compressionQuality: 1.0)?.count ?? 0
memoryCache.setObject(diskImage, forKey: cacheKey as NSString, cost: cost)
return diskImage
}
if let existingTask = activeTasks[url] {
return await existingTask.value
}
let task = Task<UIImage?, Never> {
guard let image = await download(url: url) else { return nil }
let finalImage = size.map { image.resized(to: $0) } ?? image
let cost = finalImage.jpegData(compressionQuality: 1.0)?.count ?? 0
memoryCache.setObject(finalImage, forKey: cacheKey as NSString, cost: cost)
saveToDisk(image: finalImage, key: cacheKey)
return finalImage
}
activeTasks[url] = task
let result = await task.value
activeTasks[url] = nil
return result
}
func prefetch(urls: [URL]) {
for url in urls { Task { _ = await image(for: url) } }
}
private func download(url: URL) async -> UIImage? {
guard let (data, response) = try? await URLSession.shared.data(from: url),
let http = response as? HTTPURLResponse,
(200...299).contains(http.statusCode) else { return nil }
return UIImage(data: data)
}
private func cacheKey(for url: URL, size: CGSize?) -> String {
var key = url.absoluteString
if let size { key += "_\(Int(size.width))x\(Int(size.height))" }
return key.data(using: .utf8)!.base64EncodedString().replacingOccurrences(of: "/", with: "_")
}
private func diskPath(for key: String) -> URL {
cacheDirectory.appendingPathComponent(key)
}
private func loadFromDisk(key: String) -> UIImage? {
let path = diskPath(for: key)
guard let data = try? Data(contentsOf: path) else { return nil }
return UIImage(data: data)
}
private func saveToDisk(image: UIImage, key: String) {
guard let data = image.jpegData(compressionQuality: 0.85) else { return }
try? data.write(to: diskPath(for: key), options: .atomic)
}
}Usage
import SwiftUI
struct CachedAsyncImage: View {
let url: URL
let targetSize: CGSize?
@State private var image: UIImage?
@State private var isLoading = false
var body: some View {
Group {
if let image {
Image(uiImage: image).resizable().aspectRatio(contentMode: .fill)
} else if isLoading {
ProgressView()
} else {
Color.gray.opacity(0.2)
}
}
.task {
isLoading = true
image = await ImageCache.shared.image(for: url, size: targetSize)
isLoading = false
}
}
}Notes
NSCacheautomatically handles LRU eviction and responds to system memory pressure notifications- Actor isolation eliminates data races but introduces potential
awaitsuspension points; keep critical sections small - Use
jpegData(compressionQuality: 0.85)for disk storage to balance quality vs. storage space - For progressive loading, consider storing low-resolution thumbnails with immediate display while full images download
- Add ETags or
If-Modified-Sinceheaders for conditional fetching to reduce bandwidth - Consider
URLSessionbackground download tasks for large images that should survive app suspension - Pair with
LazyVStackin SwiftUI to only load visible cells, reducing peak memory usage