Latest 2.0.1
License MIT
Platforms ios 8.0, osx 10.10, requires ARC

Build Status
Coverage Status

Carthage Compatible
CocoaPods Compatible
GitHub license
[Supported Platforms]()

YMCache is a lightweight object caching solution for iOS and Mac OS X that is designed for highly parallel access scenarios. YMCache presents a familiar interface emulating NSMutableDictionary, while internally leveraging Apple’s Grand Central Dispatch technology to strike a balance between performance and consistency.

The Yahoo Finance iOS team uses YMCache to multiplex access to it’s database of thousands of real-time stocks, which change in unpredictable ways, with an unpredictable cadence. YMCache helps relieve the complexity of multi-thread access to a central data store by providing a set of easy to understand reader-writer access semantics.

Parallel Access

  1. All read operations occur synchronously on the calling thread, but concurrently across all readers (as system resources allow).
  2. All write operations occur asynchronously
  3. Read operations initiated after a write operation will wait for the write to complete

The above rules allow for multiple readers, but a single writer. A nice result of this approach is that reads are serialized with respect to writes, enforcing a sensible order: you may read with the confidence that the expected data has been fully written.


  • Persistence: save/load a cache from disk once, or at a defined interval
  • Eviction: handle low memory situations in-band, using whatever logic suits your needs
  • Serialization: arbitrary model transformations comes for free. You can use Mantle, straight NSJSONSerialization or any other format you can think up!
  • Bulk operations: efficient multi-value reads/writes. (Bulk operations follow the Parallel Access rules, but count as a single operation)


We support the CocoaPods and Carthage distribution systems.


  1. Add YMCache to your project’s Podfile:

    target :MyApp do
      pod 'YMCache', '~> 1.0'
  2. Run pod update or pod install in your project directory.


  1. Add YMCache to your project’s Cartfile

    github "yahoo/YMCache"
  2. Run carthage update in your project directory
  3. Drag the appropriate YMCache.framework for your platform (located in $PROJECT/Carthage/Build/) into your application’s Xcode project, and add it to your target.
  4. If you are building for iOS, a new Run Script Phase must be added to copy the framework. The instructions can be found on Carthage’s getting started instructions



YMMemoryCache *cache = [YMMemoryCache memoryCacheWithName:@"my-object-cache"];
cache[@"Key1"] = valueA;
MyVal *valueA = cache[@"Key1"];
[cache addEntriesFromDictionary:@{ @"Key2": value2 }];
NSDictionary *allItems = [cache allItems];
[cache removeAllObjects];
// cache = empty; allItems = @{ @"Key1": value1, @"Key2": value2 }

This cache is essentially a completely thread-safe NSDictionary with read-write order guarantees.


Manual eviction

// Create memory cache with an eviction decider block, which will be triggered for each item in the cache whenever
// you call -purgeEvictableItems:.
YMMemoryCache cache = [YMMemoryCache memoryCacheWithName:@"my-object-cache"
key, NewsStory value, void context) {
return value.publishDate > [NSDate dateWithTimeIntervalSinceNow:-300];

dispatch_after(dispatch_time(DISPATCH_TIME_NOW, (10 * NSEC_PER_SEC)), dispatch_get_main_queue(), ^{
    [cache purgeEvictableItems:nil];
This example cache includes an eviction block which is called once after a 10 second delay. You are responsible for implementing the logic to decide which items are safe to evict. In this case, `NewsStory` models published more than 5 minutes ago will be purged from the cache. In this case, the eviction decider will be invoked on the main queue, because that is where `-purgeEvictableItems:` is called from.

##### Time-based eviction
YMMemoryCache *cache = [YMMemoryCache memoryCacheWithName:@"my-object-cache"
                                          evictionDecider:^(NSString *key, NewsStory *value, void *context) {
                                              return value.publishDate > [NSDate dateWithTimeIntervalSinceNow:-300];

cache.evictionInterval = 60.0; // trigger eviction every 60 seconds

This creates a cache periodic time-based cache evictions every 60 seconds. Note that automatic invocations of the eviction decider execute on an arbitrary background thread. This approach can be combined with other manual eviction calls to provide a situations in which cache eviction is triggered on-demand, but at lease every N minutes.

Automatic eviction on low memory

// Create memory cache with an eviction decider block, which will be triggered for each item in the cache whenever
// you call -purgeEvictableItems:.
YMMemoryCache cache = [YMMemoryCache memoryCacheWithName:@"my-object-cache"
key, NewsStory value, void context) {
return value.publishDate > [NSDate dateWithTimeIntervalSinceNow:-300];

// Trigger in-band cache eviction during low memory events.
[[NSNotificationCenter defaultCenter] addObserver:cache

// or, more commonly commonly

  • (void)didReceiveMemoryWarning {
    [super didReceiveMemoryWarning];

    // Trigger immediate synchronous cache cleanup
    [self.cache purgeEvictableItems:nil];

    The eviction decider blocks that react to low memory situations will execute on the main thread because that is the only thread that sends low memory notifications or calls `-didReceiveMemoryWarning`.

Observing Changes

YMMemoryCache *cache = [YMMemoryCache memoryCacheWithName:@"my-object-cache"];

cache.notificationInterval = 0.5;

[[NSNotificationCenter defaultCenter] addObserver:self

// from any thread, such as a network client on a background thread
cache[@"Key"] = value;

// within 0.5s (as per configuration) a notification will fire and call this:
- (void)cacheUpdated:(NSNotification *)notification {
    // Get a snapshot of all values that were added or replaced since the last notification
    NSDictionary *addedOrUpdated = notification.userInfo[kYFCacheUpdatedItemsUserInfoKey];
    // Get a set of all keys that were removed since the last notification
    NSSet *removedKeys = notification.userInfo[kYFCacheRemovedItemsUserInfoKey];

File Encryption (iOS) and writing options

The YMCachePersistenceManager uses NSData to read and write data to disk. By default, we write atomically. You may control write options by setting the persistence manager’s fileWritingOptions property before the next write.


To run the example projects, clone the repo, and run pod install from one of the directories in Example.

Example: Mantle Serialization

It’s very easy to use Mantle – version 1 or 2 – to serialize your cache to disk! Check out the pre-built, production-ready example in Examples/Mantle.

Support & Contributing

Report any bugs or send feature requests to the GitHub issues. Pull requests are very much welcomed. See CONTRIBUTING for details.


MIT license. See the LICENSE file for details.


Latest podspec

    "name": "YMCache",
    "version": "2.0.1",
    "summary": "Fast & simple small object cache. GCD-based and thread-safe.",
    "homepage": "",
    "license": "MIT",
    "authors": {
        "adamkaplan": "[email protected]"
    "source": {
        "git": "",
        "tag": "2.0.1"
    "social_media_url": "",
    "platforms": {
        "ios": "8.0",
        "osx": "10.10"
    "requires_arc": true,
    "source_files": "YMCache/*.[h,m]"

Pin It on Pinterest

Share This