A cache that enables the performant persistence of individual messages to disk.
let myCache = try CacheAdvance<MyMessageType>( file: FileManager.default.temporaryDirectory.appendingPathComponent("MyCache"), maximumBytes: 5000, shouldOverwriteOldMessages: false)
To begin caching messages, you need to create a CacheAdvance instance with:
- A file URL – this URL must represent a file that has already been created. You can create a file by using
FileManager's createFile(atPath:contents:attributes:) API.
- A maximum number of bytes on disk the cache can consume.
- Whether the cache should overwrite old messages. If you need to preserve every message, set this value to
false. If you care only about preserving recent messages, set this value to
Appending messages to disk
try myCache.append(message: aMessageInstance)
By the time the above method exits, the message will have been persisted to disk. A CacheAdvance keeps no in-memory buffer. Appending a new message is cheap, as a CacheAdvance needs to encode and persist only the new message and associated metadata.
A CacheAdvance instance that does not overwrite old messages will throw a
CacheAdvanceError.messageDataTooLarge if appending a message would exceed the cache's
maximumBytes. A CacheAdvance instance that does overwrite old messages will throw a
CacheAdvanceError.messageDataTooLarge if the message would require more than
maximumBytes to store even after evicting all older messages from the cache.
To ensure that caches can be read from 32bit devices, messages should not be larger than 2GB in size.
Retrieving messages from disk
let cachedMessages = try myCache.messages()
This method reads all cached messages from disk into memory.
CacheAdvances are not thread safe: a single CacheAdvance instance should always be interacted with from a single, serial queue. Since CacheAdvance reads from and writes to the disk synchronously, it is best to interact with a CacheAdvance on a background queue to prevent blocking the main queue.
A CacheAdvance will never fatal error: only recoverable errors will be thrown. A CacheAdvance may throw a
CacheAdvanceError, or errors related to reading or writing with
CacheAdvanceError.fileCorrupted error is thrown, the cache file is corrupt and should be deleted.
How it works
CacheAdvance immediately persists each appended messages to disk using
FileHandles. Messages are encoded using a
JSONEncoder. Messages are written to disk as an encoded data blob that is prefixed with the length of the message. The length of a message is stored using a
UInt32 to ensure that the size of the data on disk that stores a message's length is consistent between devices.
The first 64bytes of a CacheAdvance is reserved for storing metadata about the file. Any configuration data that must be static between cache opens should be stored in this header. It is also reasonable to store mutable information in the header, if doing so speeds up reads or writes to the file. The header format is managed by FileHeader.swift.
- Xcode 11.2 or later.
- iOS 12 or later.
- tvOS 12 or later.
- watchOS 5 or later.
- macOS 10.14 or later.
- Swift 5.0 or later.
Swift Package Manager
To install CacheAdvance in your iOS project with Swift Package Manager, the following lines can be added to your
dependencies: [ .package(url: "https://github.com/dfed/CacheAdvance", from: "0.3.0"), ]
To install CacheAdvance in your iOS project with CocoaPods, add the following to your
platform :ios, '12.0' pod 'CacheAdvance', '~> 0.1'
To install CacheAdvance in your iOS project with Carthage, add the following to your
carthage to build the framework and drag the built
CacheAdvance.framework into your Xcode project.
To use git submodules, checkout the submodule with
git submodule add email@example.com:dfed/CacheAdvance.git, drag CacheAdvance.xcodeproj to your project, and add CacheAdvance as a build dependency.
I’m glad you’re interested in CacheAdvance, and I’d love to see where you take it. Please read the contributing guidelines prior to submitting a Pull Request.
Thanks, and happy caching!
Package.swift in the root of the repository to open the project in Xcode.
Shout out to Peter Westen who inspired the creation of this library.
You may find interesting
0.3.0 - 2020-01-28 01:39:16
- Enabled a CacheAdvance to read a file where
overwritesOldMessagesdoesn't match what's been persisted in the cache's header, resolving #35
- Renamed the
file: URLproperty to
0.2.0 - 2020-01-22 22:20:58
- Added API to tell if a cache
isEmpty()without needing to read all
- Created differentiated
messageLargerThanRemainingCacheSize. This is a source-breaking change, as
0.1.0 - 2020-01-22 00:59:50
Store less metadata information at the end of each message, instead opting to store file metadata information in a file header.
This version is a breaking change. CacheAdvance files created using 0.0.1...0.0.3 can not be successfully opened using 0.1.0 or later.
0.0.3 - 2020-01-22 00:58:25
FileHandle API on macOS 10.15
0.0.2 - 2020-01-22 00:57:24
Add support for macOS 10.14, iOS 12, tvOS 12, and watchOS 5
0.0.1 - 2020-01-22 00:56:33
Create the first version of CacheAdvance. Append individual messages to disk in a performant way!