Swiftpack.co - Package - dfed/CacheAdvance

CacheAdvance

CI Status Swift Package Manager compatible Carthage compatible Version License Platform

A cache that enables the performant persistence of individual messages to disk.

Usage

Basic Initialization

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 true.

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.

Thread safety

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.

Error handling

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 FileHandles.

If a 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.

Requirements

  • 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.

Installation

Swift Package Manager

To install CacheAdvance in your iOS project with Swift Package Manager, the following lines can be added to your Package.swift file:

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

CocoaPods

To install CacheAdvance in your iOS project with CocoaPods, add the following to your Podfile:

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

Carthage

To install CacheAdvance in your iOS project with Carthage, add the following to your Cartfile:

github "dfed/CacheAdvance"

Run carthage to build the framework and drag the built CacheAdvance.framework into your Xcode project.

Submodules

To use git submodules, checkout the submodule with git submodule add git@github.com:dfed/CacheAdvance.git, drag CacheAdvance.xcodeproj to your project, and add CacheAdvance as a build dependency.

Contributing

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!

Developing

Double-click on Package.swift in the root of the repository to open the project in Xcode.

Attribution

Shout out to Peter Westen who inspired the creation of this library.

Github

link
Stars: 6

Dependencies

Used By

Total: 0

Releases

0.3.0 - 2020-01-28 01:39:16

  • Enabled a CacheAdvance to read a file where maximumBytes or overwritesOldMessages doesn't match what's been persisted in the cache's header, resolving #35
  • Renamed the file: URL property to fileURL: URL

0.2.0 - 2020-01-22 22:20:58

  • Added API to tell if a cache isEmpty() without needing to read all messages() into memory
  • Created differentiated Errors for messageLargerThanCacheCapacity and messageLargerThanRemainingCacheSize. This is a source-breaking change, as messageDataTooLarge was removed.

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

Use modern 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!