• Stars
    star
    1,244
  • Rank 35,526 (Top 0.8 %)
  • Language
    Objective-C
  • License
    Apache License 2.0
  • Created about 8 years ago
  • Updated 25 days ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Everyone tries to implement a cache at some point in their iOS app’s lifecycle, and this is ours.

SPTPersistentCache

Coverage Status Documentation License CocoaPods Carthage compatible Readme Score

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 8.0+
  • 💻 OS X 10.10+

Architecture 📐

SPTPersistentCache is designed as an LRU cache which makes use of the file system to store files as well as inserting a cache header into each file. This cache header allows us to track the TTL, last updated time, the redundancy check and more. This allows the cache to know how often a file is accessed, when it was made, whether it has become corrupt and allows decisions to be made on whether the cache is stale.

The use of different files rather than a single binary file allows multiple reads/writes on different files within the cache without complicated blocking logic. The cache header in each file can be removed quite easily, this can be seen in the SPTPersistentCacheViewer tool that is made to run on OS X.

Included here is also the ability to schedule garbage collection over the cache, which allows the user to ensure they are never using too much space for commonly cache data (such as images).

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.1.1'

Lastly let CocoaPods do its thing by running:

$ pod install

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

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.

NSString *cachePath = [NSSearchPathForDirectoriesInDomains(NSCachesDirectory, NSUserDomainMask, YES).firstObject stringByAppendingString:@"com.spotify.demo.image.cache"];

SPTPersistentCacheOptions *options = [SPTPersistentCacheOptions new];
options.cachePath = cachePath;
options.cacheIdentifier = @"com.spotify.demo.image.cache";
options.defaultExpirationPeriod = 60 * 60 * 24 * 30; // 30 days
options.garbageCollectionInterval = (NSUInteger)(1.5 * SPTPersistentCacheDefaultGCIntervalSec);
options.sizeConstraintBytes = 1024 * 1024 * 10; // 10 MiB
options.debugOutput = ^(NSString *string) {
    NSLog(@"%@", string);
};

SPTPersistentCache *cache = [[SPTPersistentCache alloc] initWithOptions:options];

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

Loading Data in the SPTPersistentCache

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.

Locking/Unlocking files

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 TTL

Note: That if you exceed the constrained size in your cache, even locked files can be subject to pruning.

Using the garbage collector

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

Manually managing cache usage

There are times when you may want to pre-empty a garbage collection that is scheduled, wipe the cache or simply remove all locked/unlocked files indiscriminantly. To support these cases we have provided methods to do just this.

// Lets wipe all the files we haven't explicitly locked
[self.cache wipeUnlockedFiles];
NSLog(@"Size = %@", @(self.cache.totalUsedSizeInBytes));
// Now let's wipe all the files we have explicitly locked
[self.cache wipeLockedFiles];
NSLog(@"Size = %@", @(self.cache.totalUsedSizeInBytes));
// Why not just wipe the entire cache?
[self.cache prune];
NSLog(@"Size = %@", @(self.cache.totalUsedSizeInBytes));

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.

Tools 🔨

Having a nice GUI tool to inspect the contents of an SPTPersistentCache directory would be nice, so we made one. In this repository we have a project called SPTPersistentCacheViewer.xcodeproj which is part of the SPTPersistentCache.xcworkspace. When you open it and build it for OS X, you will see a GUI that allows you to inspect the contents of a cache, including individual items TTL and payload size.

SPTPersistentCacheViewer

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

More Repositories

1

luigi

Luigi is a Python module that helps you build complex pipelines of batch jobs. It handles dependency resolution, workflow management, visualization etc. It also comes with Hadoop support built in.
Python
17,089
star
2

annoy

Approximate Nearest Neighbors in C++/Python optimized for memory usage and loading/saving to disk
C++
12,458
star
3

docker-gc

INACTIVE: Docker garbage collection of containers and images
Shell
5,068
star
4

pedalboard

🎛 🔊 A Python library for working with audio.
C++
4,748
star
5

chartify

Python library that makes it easy for data scientists to create charts.
Python
3,447
star
6

basic-pitch

A lightweight yet powerful audio-to-MIDI converter with pitch bend detection
Python
2,759
star
7

dockerfile-maven

MATURE: A set of Maven tools for dealing with Dockerfiles
Java
2,730
star
8

docker-maven-plugin

INACTIVE: A maven plugin for Docker
Java
2,652
star
9

scio

A Scala API for Apache Beam and Google Cloud Dataflow.
Scala
2,485
star
10

helios

Docker container orchestration platform
Java
2,097
star
11

web-api-examples

Basic examples to authenticate and fetch data using the Spotify Web API
HTML
1,889
star
12

HubFramework

DEPRECATED – Spotify’s component-driven UI framework for iOS
Objective-C
1,864
star
13

apollo

Java libraries for writing composable microservices
Java
1,648
star
14

dh-virtualenv

Python virtualenvs in Debian packages
Python
1,590
star
15

docker-client

INACTIVE: A simple docker client for the JVM
Java
1,425
star
16

docker-kafka

Kafka (and Zookeeper) in Docker
Shell
1,397
star
17

mobius

A functional reactive framework for managing state evolution and side-effects.
Java
1,196
star
18

sparkey

Simple constant key/value storage library, for read-heavy systems with infrequent large bulk inserts.
C
1,143
star
19

ruler

Gradle plugin which helps you analyze the size of your Android apps.
Kotlin
1,094
star
20

voyager

🛰️ Voyager is an approximate nearest-neighbor search library for Python and Java with a focus on ease of use, simplicity, and deployability.
C++
1,090
star
21

XCMetrics

XCMetrics is the easiest way to collect Xcode build metrics and improve developer productivity.
Swift
1,070
star
22

web-api

This issue tracker is no longer used. Join us in the Spotify for Developers forum for support with the Spotify Web API ➡️ https://community.spotify.com/t5/Spotify-for-Developers/bd-p/Spotify_Developer
RAML
981
star
23

echoprint-codegen

Codegen for Echoprint
C++
948
star
24

snakebite

A pure python HDFS client
Python
859
star
25

heroic

The Heroic Time Series Database
Java
843
star
26

klio

Smarter data pipelines for audio.
Python
825
star
27

XCRemoteCache

Swift
816
star
28

SPTDataLoader

The HTTP library used by the Spotify iOS client
Objective-C
624
star
29

apps-tutorial

A Spotify App that contains working examples of the use of Spotify Apps API
624
star
30

ios-sdk

Spotify SDK for iOS
Objective-C
609
star
31

JniHelpers

Tools for writing great JNI code
C++
584
star
32

postgresql-metrics

Tool that extracts and provides metrics on your PostgreSQL database
Python
583
star
33

reactochart

📈 React chart component library 📉
JavaScript
546
star
34

Mobius.swift

A functional reactive framework for managing state evolution and side-effects [Swift implementation]
Swift
539
star
35

dockerfile-mode

An emacs mode for handling Dockerfiles
Emacs Lisp
517
star
36

threaddump-analyzer

A JVM threaddump analyzer
JavaScript
481
star
37

featran

A Scala feature transformation library for data science and machine learning
Scala
467
star
38

android-sdk

Spotify SDK for Android
HTML
440
star
39

echoprint-server

Server for the Echoprint audio fingerprint system
Java
398
star
40

web-scripts

DEPRECATED: A collection of base configs and CLI wrappers used to speed up development @ Spotify.
TypeScript
382
star
41

completable-futures

Utilities for working with futures in Java 8
Java
378
star
42

SpotifyLogin

Swift framework for authenticating with the Spotify API
Swift
344
star
43

ratatool

A tool for data sampling, data generation, and data diffing
Scala
334
star
44

fmt-maven-plugin

Opinionated Maven Plugin that formats your Java code.
Java
299
star
45

big-data-rosetta-code

Code snippets for solving common big data problems in various platforms. Inspired by Rosetta Code
Scala
286
star
46

trickle

A small library for composing asynchronous code
Java
284
star
47

coordinator

A visual interface for turning an SVG into XY coördinates.
HTML
282
star
48

pythonflow

🐍 Dataflow programming for python.
Python
279
star
49

styx

"The path to execution", Styx is a service that schedules batch data processing jobs in Docker containers on Kubernetes.
Java
267
star
50

cstar

Apache Cassandra cluster orchestration tool for the command line
Python
254
star
51

netty-zmtp

A Netty implementation of ZMTP, the ZeroMQ Message Transport Protocol.
Java
242
star
52

ios-style

Guidelines for iOS development in use at Spotify
240
star
53

cassandra-reaper

Software to run automated repairs of cassandra
234
star
54

confidence

Python
232
star
55

spotify-web-api-ts-sdk

A Typescript SDK for the Spotify Web API with types for returned data.
TypeScript
231
star
56

docker-cassandra

Cassandra in Docker with fast startup
Shell
218
star
57

terraform-gke-kubeflow-cluster

Terraform module for creating GKE clusters to run Kubeflow
HCL
209
star
58

linux

Spotify's Linux kernel for Debian-based systems
C
203
star
59

git-test

test your commits
Shell
202
star
60

dns-java

DNS wrapper library that provides SRV lookup functionality
Java
201
star
61

SPStackedNav

[DEPRECATED] Navigation controller which represents its content in stacks of panes, rather than one at a time
Objective-C
195
star
62

basic-pitch-ts

A lightweight yet powerful audio-to-MIDI converter with pitch bend detection.
TypeScript
194
star
63

quickstart

A CommonJS module resolver, loader and compiler for node.js and browsers.
JavaScript
192
star
64

spotify-json

Fast and nice to use C++ JSON library.
C++
188
star
65

dbeam

DBeam exports SQL tables into Avro files using JDBC and Apache Beam
Java
181
star
66

flink-on-k8s-operator

Kubernetes operator for managing the lifecycle of Apache Flink and Beam applications.
Go
178
star
67

bazel-tools

Tools for dealing with very large Bazel-managed repositories
Java
165
star
68

lingon

A user friendly tool for building single-page JavaScript applications
JavaScript
162
star
69

dataenum

Algebraic data types in Java.
Java
159
star
70

async-google-pubsub-client

[SUNSET] Async Google Pubsub Client
Java
157
star
71

magnolify

A collection of Magnolia add-on modules
Scala
157
star
72

gcp-audit

A tool for auditing security properties of GCP projects.
Python
156
star
73

spark-bigquery

Google BigQuery support for Spark, SQL, and DataFrames
Scala
154
star
74

flo

A lightweight workflow definition library
Java
146
star
75

folsom

An asynchronous memcache client for Java
Java
144
star
76

should-up

Remove most of the "should" noise from your tests
JavaScript
143
star
77

missinglink

Build time tool for detecting link problems in java projects
Java
141
star
78

zoltar

Common library for serving TensorFlow, XGBoost and scikit-learn models in production.
Java
141
star
79

android-auth

Spotify authentication and authorization for Android. Part of the Spotify Android SDK.
HTML
139
star
80

proto-registry

An implementation of the Protobuf Registry API
TypeScript
139
star
81

futures-extra

Java library for working with Guava futures
Java
136
star
82

annoy-java

Approximate nearest neighbors in Java
Java
134
star
83

spydra

Ephemeral Hadoop clusters using Google Compute Platform
Java
132
star
84

docker-stress

Simple docker stress test and monitoring tools
Python
124
star
85

spotify-tensorflow

Provides Spotify-specific TensorFlow helpers
Python
123
star
86

spotify-web-playback-sdk-example

React based example app that creates a new player in Spotify Connect to play music from in the browse using Spotify Web Playback SDK.
JavaScript
120
star
87

crtauth

a public key backed client/server authentication system
Python
119
star
88

sparkey-java

Java implementation of the Sparkey key value store
Java
117
star
89

redux-location-state

Utilities for reading & writing Redux store state to & from the URL
JavaScript
117
star
90

rspec-dns

Easily test your DNS with RSpec
Ruby
108
star
91

web-playback-sdk

This issue tracker is no longer used. Join us in the Spotify for Developers forum for support with the Spotify Web Playback SDK ➡️ https://community.spotify.com/t5/Spotify-for-Developers/bd-p/Spotify_Developer
108
star
92

ffwd-ruby

An event and metrics fast-forwarding agent.
Ruby
106
star
93

realbook

Easier audio-based machine learning with TensorFlow.
Python
106
star
94

github-java-client

A Java client to Github API
Java
105
star
95

gimme

Creating time bound IAM Conditions with ease and flair
Python
103
star
96

super-smash-brogp

Sends and withdraws BGP prefixes for fun.
Python
98
star
97

lighthouse-audit-service

TypeScript
93
star
98

noether

Scala Aggregators used for ML Model metrics monitoring
Scala
91
star
99

python-graphwalker

Python re-implementation of the graphwalker testing tool
Python
90
star
100

spotify-js-challenge

JavaScript
87
star