Add ability to set an object level TTL

CHANGELOG.md

@@ -5,6 +5,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)
 

Source/PINCache.m

@@ -134,18 +134,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:^{
-        [_memoryCache setObject:object forKey:key withCost:cost];
+        [_memoryCache setObject:object forKey:key withCost:cost ageLimit:ageLimit];
     }];
     [group addOperation:^{
-        [_diskCache setObject:object forKey:key];
+        [_diskCache setObject:object forKey:key withAgeLimit:ageLimit];
     }];
 
     if (block) {
@@ -269,13 +279,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

Source/PINCaching.h

@@ -78,6 +78,18 @@ 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.
+ @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 +103,20 @@ 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.
+ @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>.
@@ -150,6 +176,17 @@ 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.
+ */
+- (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 +198,18 @@ 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.
+ */
+- (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.

Source/PINDiskCache.h

@@ -13,8 +13,14 @@ NS_ASSUME_NONNULL_BEGIN
 @class PINDiskCache;
 @class PINOperationQueue;
 
+extern NSString * const PINDiskCacheErrorDomain;
+extern NSErrorUserInfoKey const PINDiskCacheErrorWriteFailureCodeKey;
 extern NSString * const PINDiskCachePrefix;
 
+typedef NS_ENUM(NSInteger, PINDiskCacheError) {
+  PINDiskCacheErrorWriteFailure = -1000,
+};
+
 /**
  A callback block which provides the cache, key and object as arguments
  */
@@ -350,6 +356,17 @@ PIN_SUBCLASSING_RESTRICTED
  */
 - (void)setObjectAsync:(id <NSCoding>)object forKey:(NSString *)key completion:(nullable PINDiskCacheObjectBlock)block;
 
+/**
+ Stores an object in the cache for the specified key and age limit. This method returns immediately and executes the
+ passed block as soon as 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 ageLimit The age limit (in seconds) to associate with the 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;
+
 /**
  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
@@ -363,6 +380,20 @@ PIN_SUBCLASSING_RESTRICTED
  */
 - (void)setObjectAsync:(id <NSCoding>)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.
+ @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;
+
 /**
  Removes the object for the specified key. This method returns immediately and executes the passed block
  as soon as the object has been removed.
@@ -451,6 +482,17 @@ PIN_SUBCLASSING_RESTRICTED
  */
 - (void)setObject:(nullable id <NSCoding>)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 stored.
+
+ @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.
+ */
+- (void)setObject:(nullable id <NSCoding>)object forKey:(NSString *)key withAgeLimit:(NSTimeInterval)ageLimit;
+
 /**
  Removes objects from the cache, largest first, until the cache is equal to or smaller than the
  specified byteCount. This method blocks the calling thread until the cache has been trimmed.