CacheAdvance 2.1.0

CacheAdvance 2.1.0

×

由Dan Federman、Michael Bachand维护。

CacheAdvance 2.1.0

  • 由
  • Dan Federman

CacheAdvance

Swift Package Manager compatible codecov Version License Platform

适用于日志系统的性能缓存。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只需要对新的消息和关联的元数据进行编码和持久化。

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

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

从磁盘检索消息

let cachedMessages = try myCache.messages()
NSArray<NSData> *const cachedMessages = [cache messagesAndReturnError:nil];

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

线程安全性

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

错误处理

CacheAdvance 不会引发致命错误：只会抛出可恢复的错误。CacheAdvance 可能抛出 CacheAdvanceError，或与 FileHandle 读取或写入相关的错误。

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

工作原理

CacheAdvance 会立即使用 FileHandle 将每个附加的消息持久化到磁盘。消息默认使用 JSONEncoder 编码为 Data，尽管可以自定义编码/解码机制。消息以一个带有消息长度的编码数据块的形式写入磁盘。消息长度使用 UInt32 存储，以确保不同设备上存储消息长度所占用的磁盘数据量保持一致。

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

需求

  • Xcode 11.2 或更高版本。
  • iOS 12 或更高版本。
  • tvOS 12 或更高版本。
  • watchOS 5 或更高版本。
  • macOS 10.14 或更高版本。
  • Swift 5.0 或更高版本。

安装

Swift 包管理器

要使用 Swift 包管理器 在您的 iOS 项目中安装 CacheAdvance，以下行可以添加到您的 Package.swift 文件中

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

CocoaPods

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

platform :ios, '12.0'
pod 'CacheAdvance', '~> 1.0'

Carthage

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

github "dfed/CacheAdvance"

运行 carthage 构建框架，然后将构建的 CacheAdvance.framework 拖入您的 Xcode 项目。

子模块

要使用git子模块，请使用以下命令检出子模块： git submodule add [email protected]:dfed/CacheAdvance.git，将 CacheAdvance.xcodeproj 拖到您的项目中，并将 CacheAdvance 添加为构建依赖项。

参与贡献

很高兴看到您对 CacheAdvance 兴趣浓厚，我也很高兴看到它的发展方向。在提交 pull request 之前，请先阅读贡献指南。

谢谢，祝您缓存愉快！

开发

在仓库根目录中双击 Package.swift，以在 Xcode 中打开项目。

默认分支

此仓库的默认分支为 main。从初始提交到 151ab3f，此仓库的默认分支为 master。有关此更改为何做出的更多详细信息，请参阅 #46。

致谢

感谢Peter Westen为此库的创建提供了灵感。