CacheAdvance

一个用于日志系统的高性能缓存。CacheAdvance 持久化日志事件的速度比 SQLite 快 30 倍。

let myCache = try CacheAdvance<MyMessageType>(
    file: FileManager.default.temporaryDirectory.appendingPathComponent("MyCache"),
    maximumBytes: 5000,
    shouldOverwriteOldMessages: false)

CADCacheAdvance *const cache = [[CADCacheAdvance alloc]
                                initWithFileURL:[NSFileManager.defaultManager.temporaryDirectory URLByAppendingPathComponent:@"MyCache"]
                                maximumBytes:5000
                                shouldOverwriteOldMessages:YES
                                error:nil];

要开始缓存消息，您需要创建一个 CacheAdvance 实例，需要提供：

• 一个文件 URL – 该 URL 必须代表一个已经创建的文件。您可以使用 FileManager 的 createFile(atPath:contents:attributes:) API 来创建文件。
• 缓存可以消耗的磁盘上的最大字节数。
• 缓存是否应该覆盖旧消息。如果您需要保存每条消息，请将此值设置为 false。如果您只关心保存最近的消息，请将此值设置为 true。

try myCache.append(message: someMessage)

[cache appendMessage:someData error:nil];

到上述方法退出时，消息将被持久化到磁盘。CacheAdvance 不保留任何内存缓冲区。追加新消息的开销很小，因为 CacheAdvance 只需要编码和持久化新消息和关联的元数据。

如果追加的消息会导致超出缓存的 maximumBytes，则不覆盖旧消息的 CacheAdvance 实例将抛出 CacheAdvanceError.messageDataTooLarge。如果消息即使在从缓存中逐出所有旧消息后，仍然需要超过 maximumBytes 来存储，则覆盖旧消息的 CacheAdvance 实例将抛出 CacheAdvanceError.messageDataTooLarge。

为确保可以从 32 位设备读取缓存，消息大小不应超过 2GB。

let cachedMessages = try myCache.messages()

NSArray<NSData> *const cachedMessages = [cache messagesAndReturnError:nil];

此方法将所有缓存的消息从磁盘读取到内存中。

CacheAdvance 不是线程安全的：应该始终从单个串行队列与单个 CacheAdvance 实例交互。由于 CacheAdvance 同步地从磁盘读取和写入，因此最好在后台队列中与 CacheAdvance 交互，以防止阻塞主队列。

CacheAdvance 永远不会发生致命错误：只会抛出可恢复的错误。CacheAdvance 可能会抛出 CacheAdvanceError，或与使用 FileHandle 进行读取或写入相关的错误。

如果抛出 CacheAdvanceError.fileCorrupted 错误，则缓存文件已损坏，应删除。

CacheAdvance 使用 FileHandle 立即将每个附加的消息持久化到磁盘。默认情况下，消息使用 JSONEncoder 编码为 Data，但编码/解码机制可以自定义。消息作为编码的数据 blob 写入磁盘，该数据 blob 以消息的长度作为前缀。消息的长度使用 UInt32 存储，以确保存储消息长度的磁盘上的数据大小在设备之间保持一致。

CacheAdvance 的前 64 个字节保留用于存储有关文件的元数据。任何必须在缓存打开之间保持静态的配置数据都应存储在此标头中。如果这样做可以加快对文件的读取或写入速度，则也可以将可变信息存储在标头中。标头格式由 FileHeader.swift 管理。

• Xcode 16.0 或更高版本。
• iOS 13 或更高版本。
• tvOS 13 或更高版本。
• watchOS 6 或更高版本。
• macOS 10.15 或更高版本。
• Swift 5.10 或更高版本。

要使用 Swift Package Manager 在您的项目中安装 CacheAdvance，可以将以下行添加到您的 Package.swift 文件中

dependencies: [
    .package(url: "https://github.com/dfed/CacheAdvance", from: "3.0.0"),
]

要使用 CocoaPods 在您的项目中安装 CacheAdvance，请将以下内容添加到您的 Podfile 中

pod 'CacheAdvance', '~> 3.0'

很高兴您对 CacheAdvance 感兴趣，我很想看看您能把它带到哪里。在提交 Pull Request 之前，请阅读贡献指南。

谢谢，祝您缓存愉快！

双击存储库根目录中的 Package.swift，在 Xcode 中打开项目。

此存储库的默认分支是 main。在初始提交和151ab3f之间，此存储库的默认分支是 master。有关更改原因的更多详细信息，请参见＃46。

感谢Peter Westen，他启发了这个库的创建。

非常感谢Michael Bachand，多年来他几乎审查了对该库的每次更改。