Everyone tries to implement a cache at some point in their app’s lifecycle, and this is ours. This is a library that allows people to cache NSData with time to live (TTL) values and semantics for disk management.
- 📱 iOS 7.0+
- 💻 OS X 10.9+
SPTPersistentCache is designed as an LRU cache which stores all the data in a single binary file, with entries containing the length, last accessed time and a CRC check designed to prevent corruption. It can be used to automatically schedule garbage collection and invoke pruning.
SPTPersistentCache can be installed in a variety of ways including traditional static libraries and dynamic frameworks.
Simply include SPTPersistentCache.xcodeproj in your App’s Xcode project, and link your app with the library in the “Build Phases” section.
We are indexed on CocoaPods, which can be installed using Ruby gems:
$ gem install cocoapodsThen simply add SPTPersistentCache to your Podfile.
pod 'SPTPersistentCache', '~> 1.0'
Lastly let CocoaPods do it's thing by running:
$ cocoapods updateWe support Carthage and provide pre-built binary frameworks for all new releases. Start by making sure you have the latest version of Carthage installed, e.g. using Homebrew:
$ brew update
$ brew install carthageYou will also need to add SPTPersistentCache to your Cartfile:
github 'spotify/SPTPersistentCache' ~> 1.0
After that is all said and done, let Carthage pull in SPTPersistentCache like so:
$ carthage updateNext up, you need to add the framework to the Xcode project of your App. Lastly link the framework with your App and copy it to the App’s Frameworks directory under the “Build Phases”.
For an example of this framework's usage, see the demo application SPTPersistentCacheDemo in SPTPersistentCache.xcworkspace.
It is best to use different caches for different types of data you want to store, and not just one big cache for your entire application. However, only create one SPTPersistentCache instance for each cache, otherwise you might encounter anomalies when the two different caches end up writing to the same file.
SPTPersistentCacheOptions *options = [[SPTPersistentCacheOptions alloc] initWithCachePath:cachePath
identifier:@"com.spotify.demo.image.cache"
currentTimeCallback:nil
defaultExpirationInterval:(60 * 60 * 24 * 30)
garbageCollectorInterval:(NSUInteger)(1.5 * SPTPersistentCacheDefaultGCIntervalSec)
debug:^(NSString *string) {
NSLog(@"%@", string);
}];
options.sizeConstraintBytes = 1024 * 1024 * 10; // 10 MiB
SPTPersistentCache *cache = [[SPTPersistentCache alloc] initWithOptions:options];Note that in the above example, the currentTimeCallback is nil. When this is nil it will default to using NSDate for its current time.
When storing data in the SPTPersistentCache, you must be aware of the file system semantics. The key will be used as the file name within the cache directory to save. The reason we did not implement a hash function under the hood is because we wanted to give the option of what hash function to use to the user, so it is recommended that when you insert data into the cache for a key, that you create the key using your own hashing function (at Spotify we use SHA1, although better hashing functions exist these days). If you want the cache record, i.e. file, to exist without any TTL make sure you store it as a locked file.
NSData *data = UIImagePNGRepresentation([UIImage imageNamed:@"my-image"]);
NSString *key = @"MyHashValue";
[self.cache storeData:data
forKey:key
locked:YES
withCallback:^(SPTPersistentCacheResponse *cacheResponse) {
NSLog(@"cacheResponse = %@", cacheResponse);
} onQueue:dispatch_get_main_queue()];In order to restore data you already have saved in the SPTPersistentCache, you simply feed it the same key that you used to store the data.
NSString *key = @"MyHashValue";
[self.cache loadDataForKey:key withCallback:^(SPTPersistentCacheResponse *cacheResponse) {
UIImage *image = [UIImage imageWithData:cacheResponse.record.data];
} onQueue:dispatch_get_main_queue()];Note that if the TTL has expired, you will not receive a result.
Sometimes you may want to lock a file in SPTPersistentCache long after it has been expired by its TTL. An example of where we do this at Spotify is images relating to the cover art of the songs you have offlined (we wouldn't want to invalidate these images when you are away on vacation). When you have locked a file, you must make sure you unlock it eventually, otherwise it will stay around forever. A lock is basically a contract between the cache and it's consumer that the data will remain in the cache until it is explicitly unlocked.
NSString *key = @"MyHashValue";
[self.cache lockDataForKeys:@[key] callback:nil queue:nil];
// Now my data is safe within the arms of the cache
[self.cache unlockDataForKeys:@[key] callback:nil queue:nil];
// Now my data will be subject to its original TTLNote: That if you exceed the constrained size in your cache, even locked files can be subject to pruning.
The garbage collection functionality in SPTPersistentCache is not automatically run, you have to call it manually using scheduleGarbageCollector.
[self.cache scheduleGarbageCollection];This will schedule garbage collection on the interval you supplied in the SPTPersistentCacheOptions class, by default this is the SPTPersistentCacheDefaultExpirationTimeSec external variable. To unschedule the garbage collector simply call the opposite function unscheduleGarbageCollector.
[self.cache unscheduleGarbageCollection];At Spotify we began to standardise the way we handled images in a centralised way, and in doing so we initially created a component that was handling images and their caching. But then our requirements changed, and we began to need caching for our backend calls and preview MP3 downloads as well. In doing so, we managed to separate out our caching logic into a generic component that can be used for any piece of data.
Thus we boiled down what we needed in a cache, the key features being TTL on specific pieces of data, disk management to make sure we don't use too much, and protections against data corruption. It also became very useful to separate different caches into separate files (such as images and mp3s), in order to easily measure how much space each item is taking up.
Contributions are welcomed, have a look at the CONTRIBUTING.md document for more information.
The project is available under the Apache 2.0 license.
- Font in readme banner is “Kyrilla Sans-Serif Bold” by Manfred Klein.
- Icon in readme banner is “Treasure Chest” by Richard Cordero from the Noun Project.