Add ability to set an object level TTL

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

Source/PINCache.m

@@ -233,6 +233,26 @@ - (void)trimToDateAsync:(NSDate *)date completion:(PINCacheBlock)block
     [group start];
 }
 
+- (void)removeExpiredObjectsAsync:(PINCacheBlock)block
+{
+    PINOperationGroup *group = [PINOperationGroup asyncOperationGroupWithQueue:_operationQueue];
+
+    [group addOperation:^{
+        [_memoryCache removeExpiredObjects];
+    }];
+    [group addOperation:^{
+        [_diskCache removeExpiredObjects];
+    }];
+
+    if (block) {
+        [group setCompletion:^{
+            block(self);
+        }];
+    }
+
+    [group start];
+}
+
 #pragma mark - Public Synchronous Accessors -
 
 - (NSUInteger)diskByteCount
@@ -330,6 +350,12 @@ - (void)trimToDate:(NSDate *)date
     [_diskCache trimToDate:date];
 }
 
+- (void)removeExpiredObjects
+{
+    [_memoryCache removeExpiredObjects];
+    [_diskCache removeExpiredObjects];
+}
+
 - (void)removeAllObjects
 {
     [_memoryCache removeAllObjects];

Source/PINCaching.h

@@ -85,7 +85,8 @@ typedef void (^PINCacheObjectContainmentBlock)(BOOL containsObject);
 
  @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.
+ @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;
@@ -112,7 +113,8 @@ typedef void (^PINCacheObjectContainmentBlock)(BOOL containsObject);
  @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.
+ @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;
@@ -135,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>.
@@ -183,7 +194,8 @@ typedef void (^PINCacheObjectContainmentBlock)(BOOL containsObject);
  @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.
+ @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;
 
@@ -206,7 +218,8 @@ typedef void (^PINCacheObjectContainmentBlock)(BOOL containsObject);
  @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.
+ @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;
 
@@ -230,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.

Source/PINDiskCache.h

@@ -14,11 +14,13 @@ NS_ASSUME_NONNULL_BEGIN
 @class PINOperationQueue;
 
 extern NSString * const PINDiskCacheErrorDomain;
+extern NSErrorUserInfoKey const PINDiskCacheErrorReadFailureCodeKey;
 extern NSErrorUserInfoKey const PINDiskCacheErrorWriteFailureCodeKey;
 extern NSString * const PINDiskCachePrefix;
 
 typedef NS_ENUM(NSInteger, PINDiskCacheError) {
-  PINDiskCacheErrorWriteFailure = -1000,
+  PINDiskCacheErrorReadFailure = -1000,
+  PINDiskCacheErrorWriteFailure = -1001,
 };
 
 /**
@@ -186,6 +188,10 @@ PIN_SUBCLASSING_RESTRICTED
     - Accessing an object in the cache does not extend that object's lifetime in the cache
     - When attempting to access an object in the cache that has lived longer than self.ageLimit,
       the cache will behave as if the object does not exist
+
+ @note If an object-level age limit is set via one of the @c -setObject:forKey:withAgeLimit methods,
+ that age limit overrides self.ageLimit. The overridden object age limit could be greater or less
+ than self.agelimit but must be greater than zero.
 
  */
 @property (nonatomic, assign, getter=isTTLCache) BOOL ttlCache;
@@ -362,7 +368,8 @@ PIN_SUBCLASSING_RESTRICTED
 
  @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.
+ @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 serially after the object has been stored, or nil.
  */
 - (void)setObjectAsync:(id <NSCoding>)object forKey:(NSString *)key withAgeLimit:(NSTimeInterval)ageLimit completion:(nullable PINDiskCacheObjectBlock)block;
@@ -389,7 +396,8 @@ PIN_SUBCLASSING_RESTRICTED
  @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.
+ @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 <NSCoding>)object forKey:(NSString *)key withCost:(NSUInteger)cost ageLimit:(NSTimeInterval)ageLimit completion:(nullable PINCacheObjectBlock)block;
@@ -419,6 +427,8 @@ PIN_SUBCLASSING_RESTRICTED
 
  @param byteCount The cache will be trimmed equal to or smaller than this size.
  @param block A block to be executed serially after the cache has been trimmed, or nil.
+
+ @note This will not remove objects that have been added via one of the @c -setObject:forKey:withAgeLimit methods.
  */
 - (void)trimToSizeByDateAsync:(NSUInteger)byteCount completion:(nullable PINCacheBlock)block;
 
@@ -489,7 +499,8 @@ PIN_SUBCLASSING_RESTRICTED
  @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.
+ @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 <NSCoding>)object forKey:(NSString *)key withAgeLimit:(NSTimeInterval)ageLimit;
 
@@ -508,6 +519,8 @@ PIN_SUBCLASSING_RESTRICTED
 
  @see trimToSizeByDateAsync:
  @param byteCount The cache will be trimmed equal to or smaller than this size.
+
+ @note This will not remove objects that have been added via one of the @c -setObject:forKey:withAgeLimit methods.
  */
 - (void)trimToSizeByDate:(NSUInteger)byteCount;