CacheIndex

open class CacheIndex

In-memory sorted index of cache entries.

Maintains entries sorted by modification date ascending (oldest first). Provides O(log n) insertion via sort-after-append, O(1) lookup by filename, and O(n) removal with index shift. All mutations update totalSize atomically.

This class is intentionally standalone so multiple DiskCache instances or other consumers can share the same indexing logic without coupling to file I/O.

Usage

let index = CacheIndex()

// Build from filesystem
index.build(from: cacheURL)

// Track a new file
index.add(filename: "abc123", size: 4096)

// Mark a file as recently accessed (moves it to the end of the sorted order)
index.touch(filename: "abc123")

// Evict the oldest file
if let entry = index.popOldest() {
    try? FileManager.default.removeItem(at: cacheURL.appendingPathComponent(entry.filename))
}

// Remove a specific file
index.remove(filename: "abc123")

  • A single entry in the cache index.

    See more

    Declaration

    Swift

    public struct Entry : Equatable

  • Total allocated disk size of all tracked entries, in bytes.

    Declaration

    Swift

    open private(set) var totalSize: UInt64 { get }

  • Number of entries in the index.

    Declaration

    Swift

    open var count: Int { get }

  • Whether the index contains no entries.

    Declaration

    Swift

    open var isEmpty: Bool { get }

  • The oldest entry (smallest modificationDate), or nil if the index is empty.

    Declaration

    Swift

    open var oldest: Entry? { get }

  • All entries sorted by modification date ascending.

    Declaration

    Swift

    private var entries: [Entry]

  • Mapping from filename to index in entries.

    Declaration

    Swift

    private var entryMap: [String : Int]

  • Serializes all mutations so touch from any thread is safe with respect to controlCapacity() running on cacheQueue.

    Declaration

    Swift

    private let lock: NSRecursiveLock

  • Declaration

    Swift

    public init()

  • Builds the index by enumerating the filesystem directory.

    Discards any existing index state and replaces it with the contents of the directory. Each file’s allocated size and modification date are read via the resource keys isRegularFileKey, fileAllocatedSizeKey, and contentModificationDateKey.

    Declaration

    Swift

    @discardableResult
open func build(from directoryURL: URL) -> UInt64

    Parameters

    directoryURL

    The cache directory URL to enumerate.

    Return Value

    The total allocated size of all files found.

  • Inserts or replaces an entry in the index.

    If an entry with the same filename already exists, it is removed first. The entry’s modification date defaults to the current date when nil.

    Declaration

    Swift

    open func add(filename: String, size: UInt64, modificationDate: Date? = nil)

    Parameters

    filename

    MD5 filename of the cached file.
    size

    Allocated disk size in bytes.
    modificationDate

    File modification date. Pass nil to use the current date.

  • Updates the modification date of an existing entry.

    Does nothing if no entry with the given filename exists. The modification date defaults to the current date when nil.

    Declaration

    Swift

    open func touch(filename: String, modificationDate: Date? = nil)

    Parameters

    filename

    MD5 filename of the cached file.
    modificationDate

    New modification date. Pass nil to use the current date.

  • Removes an entry from the index by filename.

    Does nothing and does not produce an error if the filename is not in the index.

    Declaration

    Swift

    open func remove(filename: String)

    Parameters

    filename

    MD5 filename of the cached file to remove.

  • Removes all entries from the index and resets totalSize to zero.

    Declaration

    Swift

    open func removeAll()

  • Removes and returns the oldest entry.

    Declaration

    Swift

    open func popOldest() -> Entry?

    Return Value

    The entry with the smallest modificationDate, or nil if the index is empty.

  • Rebuilds the filename→index mapping from the sorted entries array.

    Declaration

    Swift

    private func rebuildEntryMap()