pinterest · garrettmoon · May 11, 2018 · Dec 5, 2017 · Dec 5, 2017 · Dec 5, 2017
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,7 @@
 ## 3.0.1 -- Beta 6
 - [fix] Add some sane limits to the disk cache: [#201]https://github.com/pinterest/PINCache/pull/201
 - [new] Update enumeration methods to allow a stop flag to be flipped by caller: [#204](https://github.com/pinterest/PINCache/pull/204)
+- [new] Add ability to set an object level TTL: [#209](https://github.com/pinterest/PINCache/pull/209)
 - [performance] Improves cache miss performance by ~2 orders of magnitude on device: [#202](https://github.com/pinterest/PINCache/pull/202)
 - [performance] Significantly improve startup performance: [#203](https://github.com/pinterest/PINCache/pull/203)
 

diff --git a/PINCache.xcodeproj/project.pbxproj b/PINCache.xcodeproj/project.pbxproj
@@ -18,6 +18,9 @@
 		6928EED31E4160EE00B5D975 /* PINCaching.h in Headers */ = {isa = PBXBuildFile; fileRef = 6928EED21E4160EE00B5D975 /* PINCaching.h */; settings = {ATTRIBUTES = (Public, ); }; };
 		6928EED41E4160FE00B5D975 /* PINCaching.h in Headers */ = {isa = PBXBuildFile; fileRef = 6928EED21E4160EE00B5D975 /* PINCaching.h */; settings = {ATTRIBUTES = (Public, ); }; };
 		6928EED51E41610700B5D975 /* PINCaching.h in Headers */ = {isa = PBXBuildFile; fileRef = 6928EED21E4160EE00B5D975 /* PINCaching.h */; settings = {ATTRIBUTES = (Public, ); }; };
+		C30EE1F520373D1900D78CB9 /* NSDate+PINCacheTests.m in Sources */ = {isa = PBXBuildFile; fileRef = C30EE1EA203717DE00D78CB9 /* NSDate+PINCacheTests.m */; };
+		C30EE1F620373D1A00D78CB9 /* NSDate+PINCacheTests.m in Sources */ = {isa = PBXBuildFile; fileRef = C30EE1EA203717DE00D78CB9 /* NSDate+PINCacheTests.m */; };
+		C30EE1F720373D1B00D78CB9 /* NSDate+PINCacheTests.m in Sources */ = {isa = PBXBuildFile; fileRef = C30EE1EA203717DE00D78CB9 /* NSDate+PINCacheTests.m */; };
 		CC0105DF1E271A5C00890935 /* PINCache.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = CC0105B11E271A1600890935 /* PINCache.framework */; };
 		CC0105EE1E271A6400890935 /* PINCache.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = CC0105C11E271A4000890935 /* PINCache.framework */; };
 		CC01060E1E271A9500890935 /* PINCache.m in Sources */ = {isa = PBXBuildFile; fileRef = CC0106061E271A9000890935 /* PINCache.m */; };
@@ -172,6 +175,8 @@
 		6818C2901E564C1100875DB7 /* PINOperation.xcodeproj */ = {isa = PBXFileReference; lastKnownFileType = "wrapper.pb-project"; name = PINOperation.xcodeproj; path = Carthage/Checkouts/PINOperation/PINOperation.xcodeproj; sourceTree = "<group>"; };
 		68A0FBFF1E4D3282000B552D /* PINCacheMacros.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = PINCacheMacros.h; sourceTree = "<group>"; };
 		6928EED21E4160EE00B5D975 /* PINCaching.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = PINCaching.h; sourceTree = "<group>"; };
+		C30EE1E9203717DE00D78CB9 /* NSDate+PINCacheTests.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = "NSDate+PINCacheTests.h"; sourceTree = "<group>"; };
+		C30EE1EA203717DE00D78CB9 /* NSDate+PINCacheTests.m */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.objc; path = "NSDate+PINCacheTests.m"; sourceTree = "<group>"; };
 		CC0105B11E271A1600890935 /* PINCache.framework */ = {isa = PBXFileReference; explicitFileType = wrapper.framework; includeInIndex = 0; path = PINCache.framework; sourceTree = BUILT_PRODUCTS_DIR; };
 		CC0105C11E271A4000890935 /* PINCache.framework */ = {isa = PBXFileReference; explicitFileType = wrapper.framework; includeInIndex = 0; path = PINCache.framework; sourceTree = BUILT_PRODUCTS_DIR; };
 		CC0105CE1E271A4900890935 /* PINCache.framework */ = {isa = PBXFileReference; explicitFileType = wrapper.framework; includeInIndex = 0; path = PINCache.framework; sourceTree = BUILT_PRODUCTS_DIR; };
@@ -313,6 +318,8 @@
 			children = (
 				CC0106CB1E28248A00890935 /* Assets */,
 				CC0106C51E281D6900890935 /* Info.plist */,
+				C30EE1E9203717DE00D78CB9 /* NSDate+PINCacheTests.h */,
+				C30EE1EA203717DE00D78CB9 /* NSDate+PINCacheTests.m */,
 				CC0106C91E28228300890935 /* PINCacheTests.h */,
 				CC01060D1E271A9000890935 /* PINCacheTests.m */,
 			);
@@ -672,6 +679,7 @@
 			buildActionMask = 2147483647;
 			files = (
 				CC0106C61E28226900890935 /* PINCacheTests.m in Sources */,
+				C30EE1F520373D1900D78CB9 /* NSDate+PINCacheTests.m in Sources */,
 			);
 			runOnlyForDeploymentPostprocessing = 0;
 		};
@@ -680,6 +688,7 @@
 			buildActionMask = 2147483647;
 			files = (
 				CC0106C71E28226A00890935 /* PINCacheTests.m in Sources */,
+				C30EE1F620373D1A00D78CB9 /* NSDate+PINCacheTests.m in Sources */,
 			);
 			runOnlyForDeploymentPostprocessing = 0;
 		};
@@ -688,6 +697,7 @@
 			buildActionMask = 2147483647;
 			files = (
 				CC0106C81E28226A00890935 /* PINCacheTests.m in Sources */,
+				C30EE1F720373D1B00D78CB9 /* NSDate+PINCacheTests.m in Sources */,
 			);
 			runOnlyForDeploymentPostprocessing = 0;
 		};

diff --git a/Source/PINCache.h b/Source/PINCache.h
@@ -103,6 +103,27 @@ PIN_SUBCLASSING_RESTRICTED
                   serializer:(nullable PINDiskCacheSerializerBlock)serializer
                 deserializer:(nullable PINDiskCacheDeserializerBlock)deserializer;
 
+/**
+ Multiple instances with the same name are *not* allowed and can *not* safely
+ access the same data on disk. Also used to create the <diskCache>.
+ Initializer allows you to override default NSKeyedArchiver/NSKeyedUnarchiver serialization for <diskCache>.
+ You must provide both serializer and deserializer, or opt-out to default implementation providing nil values.
+
+ @see name
+ @param name The name of the cache.
+ @param rootPath The path of the cache on disk.
+ @param serializer   A block used to serialize object before writing to disk. If nil provided, default NSKeyedArchiver serialized will be used.
+ @param deserializer A block used to deserialize object read from disk. If nil provided, default NSKeyedUnarchiver serialized will be used.
+ @param keyEncoder A block used to encode key(filename). If nil provided, default url encoder will be used
+ @param keyDecoder A block used to decode key(filename). If nil provided, default url decoder will be used
+ @result A new cache with the specified name.
+ */
+- (instancetype)initWithName:(nonnull NSString *)name
+                    rootPath:(nonnull NSString *)rootPath
+                  serializer:(nullable PINDiskCacheSerializerBlock)serializer
+                deserializer:(nullable PINDiskCacheDeserializerBlock)deserializer
+                  keyEncoder:(nullable PINDiskCacheKeyEncoderBlock)keyEncoder
+                  keyDecoder:(nullable PINDiskCacheKeyDecoderBlock)keyDecoder;
 
 /**
  Multiple instances with the same name are *not* allowed and can *not* safely
@@ -117,14 +138,16 @@ PIN_SUBCLASSING_RESTRICTED
  @param deserializer A block used to deserialize object read from disk. If nil provided, default NSKeyedUnarchiver serialized will be used.
  @param keyEncoder A block used to encode key(filename). If nil provided, default url encoder will be used
  @param keyDecoder A block used to decode key(filename). If nil provided, default url decoder will be used
+ @param ttlCache Whether or not the cache should behave as a TTL cache.
  @result A new cache with the specified name.
  */
 - (instancetype)initWithName:(nonnull NSString *)name
                     rootPath:(nonnull NSString *)rootPath
                   serializer:(nullable PINDiskCacheSerializerBlock)serializer
                 deserializer:(nullable PINDiskCacheDeserializerBlock)deserializer
                   keyEncoder:(nullable PINDiskCacheKeyEncoderBlock)keyEncoder
-                  keyDecoder:(nullable PINDiskCacheKeyDecoderBlock)keyDecoder NS_DESIGNATED_INITIALIZER;
+                  keyDecoder:(nullable PINDiskCacheKeyDecoderBlock)keyDecoder
+                    ttlCache:(BOOL)ttlCache NS_DESIGNATED_INITIALIZER;
 
 @end
 

diff --git a/Source/PINCache.m b/Source/PINCache.m
@@ -44,6 +44,17 @@ - (instancetype)initWithName:(NSString *)name
                 deserializer:(PINDiskCacheDeserializerBlock)deserializer
                   keyEncoder:(PINDiskCacheKeyEncoderBlock)keyEncoder
                   keyDecoder:(PINDiskCacheKeyDecoderBlock)keyDecoder
+{
+    return [self initWithName:name rootPath:rootPath serializer:serializer deserializer:deserializer keyEncoder:keyEncoder keyDecoder:keyDecoder ttlCache:NO];
+}
+
+- (instancetype)initWithName:(NSString *)name
+                    rootPath:(NSString *)rootPath
+                  serializer:(PINDiskCacheSerializerBlock)serializer
+                deserializer:(PINDiskCacheDeserializerBlock)deserializer
+                  keyEncoder:(PINDiskCacheKeyEncoderBlock)keyEncoder
+                  keyDecoder:(PINDiskCacheKeyDecoderBlock)keyDecoder
+                    ttlCache:(BOOL)ttlCache
 {
     if (!name)
         return nil;
@@ -60,7 +71,8 @@ - (instancetype)initWithName:(NSString *)name
                                            deserializer:deserializer
                                              keyEncoder:nil
                                              keyDecoder:nil
-                                         operationQueue:_operationQueue];
+                                         operationQueue:_operationQueue
+                                               ttlCache:ttlCache];
         _memoryCache = [[PINMemoryCache alloc] initWithOperationQueue:_operationQueue];
     }
     return self;
@@ -134,18 +146,28 @@ - (void)setObjectAsync:(id <NSCoding>)object forKey:(NSString *)key completion:(
     [self setObjectAsync:object forKey:key withCost:0 completion:block];
 }
 
+- (void)setObjectAsync:(id <NSCoding>)object forKey:(NSString *)key withAgeLimit:(NSTimeInterval)ageLimit completion:(PINCacheObjectBlock)block
+{
+    [self setObjectAsync:object forKey:key withCost:0 ageLimit:ageLimit completion:block];
+}
+
 - (void)setObjectAsync:(id <NSCoding>)object forKey:(NSString *)key withCost:(NSUInteger)cost completion:(PINCacheObjectBlock)block
+{
+    [self setObjectAsync:object forKey:key withCost:cost ageLimit:0.0 completion:block];
+}
+
+- (void)setObjectAsync:(nonnull id)object forKey:(nonnull NSString *)key withCost:(NSUInteger)cost ageLimit:(NSTimeInterval)ageLimit completion:(nullable PINCacheObjectBlock)block
 {
     if (!key || !object)
         return;
 
     PINOperationGroup *group = [PINOperationGroup asyncOperationGroupWithQueue:_operationQueue];
 
     [group addOperation:^{
-        [self->_memoryCache setObject:object forKey:key withCost:cost];
+        [self->_memoryCache setObject:object forKey:key withCost:cost ageLimit:ageLimit];
     }];
     [group addOperation:^{
-        [self->_diskCache setObject:object forKey:key];
+        [self->_diskCache setObject:object forKey:key withAgeLimit:ageLimit];
     }];
 
     if (block) {
@@ -223,6 +245,26 @@ - (void)trimToDateAsync:(NSDate *)date completion:(PINCacheBlock)block
     [group start];
 }
 
+- (void)removeExpiredObjectsAsync:(PINCacheBlock)block
+{
+    PINOperationGroup *group = [PINOperationGroup asyncOperationGroupWithQueue:_operationQueue];
+
+    [group addOperation:^{
+        [self->_memoryCache removeExpiredObjects];
+    }];
+    [group addOperation:^{
+        [self->_diskCache removeExpiredObjects];
+    }];
+
+    if (block) {
+        [group setCompletion:^{
+            block(self);
+        }];
+    }
+
+    [group start];
+}
+
 #pragma mark - Public Synchronous Accessors -
 
 - (NSUInteger)diskByteCount
@@ -269,13 +311,23 @@ - (void)setObject:(id <NSCoding>)object forKey:(NSString *)key
     [self setObject:object forKey:key withCost:0];
 }
 
+- (void)setObject:(id <NSCoding>)object forKey:(NSString *)key withAgeLimit:(NSTimeInterval)ageLimit
+{
+    [self setObject:object forKey:key withCost:0 ageLimit:ageLimit];
+}
+
 - (void)setObject:(id <NSCoding>)object forKey:(NSString *)key withCost:(NSUInteger)cost
+{
+    [self setObject:object forKey:key withCost:cost ageLimit:0.0];
+}
+
+- (void)setObject:(nullable id)object forKey:(nonnull NSString *)key withCost:(NSUInteger)cost ageLimit:(NSTimeInterval)ageLimit
 {
     if (!key || !object)
         return;
 
-    [_memoryCache setObject:object forKey:key withCost:cost];
-    [_diskCache setObject:object forKey:key];
+    [_memoryCache setObject:object forKey:key withCost:cost ageLimit:ageLimit];
+    [_diskCache setObject:object forKey:key withAgeLimit:ageLimit];
 }
 
 - (nullable id)objectForKeyedSubscript:(NSString *)key
@@ -310,6 +362,12 @@ - (void)trimToDate:(NSDate *)date
     [_diskCache trimToDate:date];
 }
 
+- (void)removeExpiredObjects
+{
+    [_memoryCache removeExpiredObjects];
+    [_diskCache removeExpiredObjects];
+}
+
 - (void)removeAllObjects
 {
     [_memoryCache removeAllObjects];

diff --git a/Source/PINCaching.h b/Source/PINCaching.h
@@ -78,6 +78,19 @@ typedef void (^PINCacheObjectContainmentBlock)(BOOL containsObject);
  */
 - (void)setObjectAsync:(id)object forKey:(NSString *)key completion:(nullable PINCacheObjectBlock)block;
 
+/**
+ Stores an object in the cache for the specified key and the specified age limit. This method returns immediately
+ and executes the passed block after the object has been stored, potentially in parallel with other blocks
+ on the <concurrentQueue>.
+
+ @param object An object to store in the cache.
+ @param key A key to associate with the object. This string will be copied.
+ @param ageLimit The age limit (in seconds) to associate with the object. An age limit <= 0 means there is no object-level age limit and the
+                 cache-level TTL will be used for this object.
+ @param block A block to be executed concurrently after the object has been stored, or nil.
+ */
+- (void)setObjectAsync:(id)object forKey:(NSString *)key withAgeLimit:(NSTimeInterval)ageLimit completion:(nullable PINCacheObjectBlock)block;
+
 /**
  Stores an object in the cache for the specified key and the specified memory cost. If the cost causes the total
  to go over the <memoryCache.costLimit> the cache is trimmed (oldest objects first). This method returns immediately
@@ -91,6 +104,21 @@ typedef void (^PINCacheObjectContainmentBlock)(BOOL containsObject);
  */
 - (void)setObjectAsync:(id)object forKey:(NSString *)key withCost:(NSUInteger)cost completion:(nullable PINCacheObjectBlock)block;
 
+/**
+ Stores an object in the cache for the specified key and the specified memory cost and age limit. If the cost causes the total
+ to go over the <memoryCache.costLimit> the cache is trimmed (oldest objects first). This method returns immediately
+ and executes the passed block after the object has been stored, potentially in parallel with other blocks
+ on the <concurrentQueue>.
+
+ @param object An object to store in the cache.
+ @param key A key to associate with the object. This string will be copied.
+ @param cost An amount to add to the <memoryCache.totalCost>.
+ @param ageLimit The age limit (in seconds) to associate with the object. An age limit <= 0 means there is no object-level age limit and the cache-level TTL will be
+                 used for this object.
+ @param block A block to be executed concurrently after the object has been stored, or nil.
+ */
+- (void)setObjectAsync:(id)object forKey:(NSString *)key withCost:(NSUInteger)cost ageLimit:(NSTimeInterval)ageLimit completion:(nullable PINCacheObjectBlock)block;
+
 /**
  Removes the object for the specified key. This method returns immediately and executes the passed
  block after the object has been removed, potentially in parallel with other blocks on the <concurrentQueue>.
@@ -109,6 +137,15 @@ typedef void (^PINCacheObjectContainmentBlock)(BOOL containsObject);
  */
 - (void)trimToDateAsync:(NSDate *)date completion:(nullable PINCacheBlock)block;
 
+/**
+ Removes all expired objects from the cache. This includes objects that are considered expired due to the cache-level ageLimit
+ as well as object-level ageLimits. This method returns immediately and executes the passed block after the objects have been removed,
+ potentially in parallel with other blocks on the <concurrentQueue>.
+
+ @param block A block to be executed concurrently after the objects have been removed, or nil.
+ */
+- (void)removeExpiredObjectsAsync:(nullable PINCacheBlock)block;
+
 /**
  Removes all objects from the cache.This method returns immediately and executes the passed block after the
  cache has been cleared, potentially in parallel with other blocks on the <concurrentQueue>.
@@ -150,6 +187,18 @@ typedef void (^PINCacheObjectContainmentBlock)(BOOL containsObject);
  */
 - (void)setObject:(nullable id)object forKey:(NSString *)key;
 
+/**
+ Stores an object in the cache for the specified key and age limit. This method blocks the calling thread until the
+ object has been set. Uses a lock to achieve synchronicity on the disk cache.
+
+ @see setObjectAsync:forKey:completion:
+ @param object An object to store in the cache.
+ @param key A key to associate with the object. This string will be copied.
+ @param ageLimit The age limit (in seconds) to associate with the object. An age limit <= 0 means there is no
+                 object-level age limit and the cache-level TTL will be used for this object.
+ */
+- (void)setObject:(nullable id)object forKey:(NSString *)key withAgeLimit:(NSTimeInterval)ageLimit;
+
 /**
  Stores an object in the cache for the specified key and the specified memory cost. If the cost causes the total
  to go over the <memoryCache.costLimit> the cache is trimmed (oldest objects first). This method blocks the calling thread
@@ -161,6 +210,19 @@ typedef void (^PINCacheObjectContainmentBlock)(BOOL containsObject);
  */
 - (void)setObject:(nullable id)object forKey:(NSString *)key withCost:(NSUInteger)cost;
 
+/**
+ Stores an object in the cache for the specified key and the specified memory cost and age limit. If the cost causes the total
+ to go over the <memoryCache.costLimit> the cache is trimmed (oldest objects first). This method blocks the calling thread
+ until the object has been stored.
+
+ @param object An object to store in the cache.
+ @param key A key to associate with the object. This string will be copied.
+ @param cost An amount to add to the <memoryCache.totalCost>.
+ @param ageLimit The age limit (in seconds) to associate with the object. An age limit <= 0 means there is no object-level age
+                 limit and the cache-level TTL will be used for this object.
+ */
+- (void)setObject:(nullable id)object forKey:(NSString *)key withCost:(NSUInteger)cost ageLimit:(NSTimeInterval)ageLimit;
+
 /**
  Removes the object for the specified key. This method blocks the calling thread until the object
  has been removed.
@@ -181,6 +243,13 @@ typedef void (^PINCacheObjectContainmentBlock)(BOOL containsObject);
  */
 - (void)trimToDate:(NSDate *)date;
 
+/**
+ Removes all expired objects from the cache. This includes objects that are considered expired due to the cache-level ageLimit
+ as well as object-level ageLimits. This method blocks the calling thread until the objects have been removed.
+ Uses a lock to achieve synchronicity on the disk cache.
+ */
+- (void)removeExpiredObjects;
+
 /**
  Removes all objects from the cache. This method blocks the calling thread until the cache has been cleared.
  Uses a lock to achieve synchronicity on the disk cache.