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+

Architecture 📐

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.

Installation

SPTPersistentCache can be installed in a variety of ways including traditional static libraries and dynamic frameworks.

Static Library

Simply include SPTPersistentCache.xcodeproj in your App’s Xcode project, and link your app with the library in the “Build Phases” section.

CocoaPods

We are indexed on CocoaPods, which can be installed using Ruby gems:

$ gem install cocoapods

Then simply add SPTPersistentCache to your Podfile.

pod 'SPTPersistentCache', '~> 1.0'

Lastly let CocoaPods do it's thing by running:

$ cocoapods update

Carthage

We 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 carthage

You 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 update

Next 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”.

Usage example 👀

For an example of this framework's usage, see the demo application SPTPersistentCacheDemo in SPTPersistentCache.xcworkspace.

Creating the SPTPersistentCache

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.

Storing Data in the SPTPersistentCache

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()];

Background story 📖

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.

Contributing 📬

Contributions are welcomed, have a look at the CONTRIBUTING.md document for more information.

License 📝

The project is available under the Apache 2.0 license.

Acknowledgements

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