WIP: First compiling implementation (untested) of support for self expiring cache results -- that control & construct their own Cache item policy from the cache item factory logic and data only available at runtime from the results within the execution of the cache item factory.

Author: cajuncoding

LazyCacheHelpers/CacheHelpers/LazyCachePolicy.cs

@@ -66,7 +66,7 @@ public static CacheItemPolicy NewAbsoluteExpirationPolicy(TimeSpan cacheTimeSpan
         private static readonly ThreadLocal<Random> _threadLocalRandomGenerator = new ThreadLocal<Random>(() => new Random(Guid.NewGuid().GetHashCode()));
 
         /// <summary>
-        /// Provides logic to randomly distribute Cache TTL values within the specified threshhold to help ensure that
+        /// Provides logic to randomly distribute Cache TTL values within the specified threshold to help ensure that
         ///     cached values are not all exactly equal.  This is helpful to provide dynamic caching that is much less likely
         ///     to result in all elements being expired from cache at the exact same time, but balances this with the fact that
         ///     they should expire relatively close in time.  So the Threshold value should be small; e.g. with 30 seconds, or
@@ -84,7 +84,7 @@ public static TimeSpan RandomizeCacheTTLDistribution(TimeSpan timeSpanTTL, int m
             //BBernard
             //Salt the timespan with a small randomly generated offset value (e.g. spice it up a little with some salt)!
             //NOTE: We use a random number generator to help us salt our Cache intervals and better
-            //  stimilate offset caching of items.  This is a simplistic way to help level out the 
+            //  stimulate offset caching of items.  This is a simplistic way to help level out the 
             //  cache hit/miss distribution so that fewer requests take the same large hit to refresh
             //  when they expire by absolute time.
             //For Example: If in a high load environment multiple requests could all result in cache misses

LazyCacheHelpers/CacheInterfaces/ILazyCacheHandlerSelfExpiringResults.cs

@@ -0,0 +1,26 @@
+using System;
+using System.Runtime.Caching;
+using System.Threading.Tasks;
+
+namespace LazyCacheHelpers
+{
+    /// <summary>
+    /// BBernard
+    /// Original Source (MIT License): https://github.com/cajuncoding/LazyCacheHelpers
+    /// 
+    /// Public Interface for the Lazy Cache Handler which adds support for the value factories to be self-managing/self-expiring
+    /// by returning both the result and the policy!  This is very useful in use cases such as loading Auth Tokens or other
+    /// data from external APIs whereby the API response determines how long the result is valid for, and therefore it does
+    /// not need to be refreshed/reloaded until that time has lapsed. So the logic can build a Cache Expiration policy based
+    /// on the information in the response and create a valid CachePolicy.
+    ///
+    /// NOTE: This is intended to be an extension of the base ILazyCacheHandler, but is separate now as a composable interface to
+    /// to mitigate potentially breaking existing custom implementations of the ILazyCacheHandler.
+    /// </summary>
+    /// <typeparam name="TValue"></typeparam>
+    public interface ILazyCacheHandlerSelfExpiringResults<TValue>
+    {
+        TValue GetOrAddFromCache<TKey>(TKey key, Func<ILazySelfExpiringCacheResult<TValue>> fnValueFactory);
+        Task<TValue> GetOrAddFromCacheAsync<TKey>(TKey key, Func<Task<ILazySelfExpiringCacheResult<TValue>>> fnAsyncValueFactory);
+    }
+}

LazyCacheHelpers/CacheInterfaces/ILazySelfExpiringCacheResult.cs

@@ -0,0 +1,10 @@
+using System.Runtime.Caching;
+
+namespace LazyCacheHelpers
+{
+    public interface ILazySelfExpiringCacheResult<out TValue>
+    {
+        CacheItemPolicy CachePolicy { get; }
+        TValue CacheItem { get; }
+    }
+}

LazyCacheHelpers/CacheRepositories/LazySelfExpiringCacheResult.cs

@@ -0,0 +1,28 @@
+using System;
+using System.Runtime.Caching;
+
+namespace LazyCacheHelpers
+{
+    public class LazySelfExpiringCacheResult<TValue> : ILazySelfExpiringCacheResult<TValue>
+    {
+        public LazySelfExpiringCacheResult(TValue cacheItem, ILazyCachePolicy cachePolicy)
+            : this(cacheItem, cachePolicy?.GeneratePolicy())
+        { }
+
+        public LazySelfExpiringCacheResult(TValue cacheItem, CacheItemPolicy cachePolicy)
+        {
+            CacheItem = cacheItem;
+            CachePolicy = cachePolicy ?? throw new ArgumentNullException(nameof(cachePolicy));
+        }
+
+        public CacheItemPolicy CachePolicy { get; }
+
+        public TValue CacheItem { get; }
+
+        public static LazySelfExpiringCacheResult<TValue> NewAbsoluteExpirationResult(TValue cacheItem, int absoluteExpirationMillis)
+            => NewAbsoluteExpirationResult(cacheItem, TimeSpan.FromMilliseconds(absoluteExpirationMillis));
+
+        public static LazySelfExpiringCacheResult<TValue> NewAbsoluteExpirationResult(TValue cacheItem, TimeSpan absoluteExpirationTimeSpan)
+            => new LazySelfExpiringCacheResult<TValue>(cacheItem, LazyCachePolicy.NewAbsoluteExpirationPolicy(absoluteExpirationTimeSpan));
+    }
+}

LazyCacheHelpers/DefaultLazyCache.cs

@@ -56,8 +56,29 @@ public static TValue GetOrAddFromCache<TKey, TValue>(TKey key, Func<TValue> fnVa
             where TValue : class
         {
             TValue result = LazyCachePolicy.IsPolicyEnabled(cacheItemPolicy)
-                                ? (TValue) _lazyCache.GetOrAddFromCache(key, fnValueFactory, cacheItemPolicy)
-                                : fnValueFactory();
+                ? (TValue) _lazyCache.GetOrAddFromCache(key, fnValueFactory, cacheItemPolicy)
+                : fnValueFactory();
+            return result;
+        }
+
+        /// <summary>
+        /// Add or update the cache with the specified cache key and item that will be Lazy Initialized from Lambda function/logic.
+        /// In this overload the logic must also construct and return the result as well as the cache expiration policy together
+        /// as any implementation of ILazySelfExpiringCacheResult&lt;TValue&gt; of which a default implementation can be easily
+        /// created from LazySelfExpiringCacheResult&lt;TValue&gt;.NewAbsoluteExpirationResult(...).
+        /// 
+        /// This method ensures that the item is initialized with full thread safety and that only one thread ever executes the work
+        /// to initialize the item to be cached (Self-populated Cache) -- significantly improving server utilization and performance.
+        /// </summary>
+        /// <typeparam name="TKey"></typeparam>
+        /// <typeparam name="TValue"></typeparam>
+        /// <param name="key"></param>
+        /// <param name="fnValueFactory"></param>
+        /// <returns></returns>
+        public static TValue GetOrAddFromCache<TKey, TValue>(TKey key, Func<ILazySelfExpiringCacheResult<TValue>> fnValueFactory)
+            where TValue : class
+        {
+            var result = (TValue)_lazyCache.GetOrAddFromCache(key, fnValueFactory);
             return result;
         }
 
@@ -98,9 +119,34 @@ public static async Task<TValue> GetOrAddFromCacheAsync<TKey, TValue>(TKey key,
             var wrappedFnValueFactory = new Func<Task<object>>(async () => await fnAsyncValueFactory());
 
             TValue result = LazyCachePolicy.IsPolicyEnabled(cacheItemPolicy)
-                                ? (TValue) await _lazyCache.GetOrAddFromCacheAsync(key, wrappedFnValueFactory, cacheItemPolicy)
-                                : await fnAsyncValueFactory();
+                ? (TValue)await _lazyCache.GetOrAddFromCacheAsync(key, wrappedFnValueFactory, cacheItemPolicy)
+                : await fnAsyncValueFactory();
+
+            return result;
+        }
+
+        /// <summary>
+        /// Add or update the cache with the specified cache key and item that will be Lazy Initialized from Lambda function/logic.
+        /// In this overload the logic must also construct and return the result as well as the cache expiration policy together
+        /// as any implementation of ILazySelfExpiringCacheResult&lt;TValue&gt; of which a default implementation can be easily
+        /// created from LazySelfExpiringCacheResult&lt;TValue&gt;.NewAbsoluteExpirationResult(...).
+        /// 
+        /// This method ensures that the item is initialized with full thread safety and that only one thread ever executes the work
+        /// to initialize the item to be cached (Self-populated Cache) -- significantly improving server utilization and performance.
+        /// </summary>
+        /// <typeparam name="TKey"></typeparam>
+        /// <typeparam name="TValue"></typeparam>
+        /// <param name="key"></param>
+        /// <param name="fnAsyncValueFactory"></param>
+        /// <returns></returns>
+        public static async Task<TValue> GetOrAddFromCacheAsync<TKey, TValue>(TKey key, Func<Task<ILazySelfExpiringCacheResult<TValue>>> fnAsyncValueFactory)
+            where TValue : class
+        {
+            //Because the underlying cache is set up to store any object and the async coercion isn't as easy as the synchronous,
+            //  we must wrap the original generics typed async factory into a new Func<> that matches the required type.
+            var wrappedFnValueFactory = new Func<Task<ILazySelfExpiringCacheResult<object>>>(async () => await fnAsyncValueFactory());
 
+            var result = (TValue)await _lazyCache.GetOrAddFromCacheAsync(key, wrappedFnValueFactory);
             return result;
         }
 

LazyCacheHelpers/LazyCacheHandler.cs

@@ -23,7 +23,7 @@ namespace LazyCacheHelpers
     /// NOTE: A wrapper implementation for MemoryCache is implemented (via default ICacheRepository implementation as LazyDotNetMemoryCacheRepository) to 
     ///     make working with MemoryCache with greatly simplified support for self-populating (Lazy) initialization.
     /// </summary>
-    public class LazyCacheHandler<TValue> : ILazyCacheHandler<TValue> where TValue : class
+    public class LazyCacheHandler<TValue> : ILazyCacheHandler<TValue>, ILazyCacheHandlerSelfExpiringResults<TValue> where TValue : class
     {
         //Added methods to CacheHelper to work with MemoryCache more easily.
         //NOTE: .Net MemoryCache supports this does NOT support Garbage Collection and Resource Reclaiming so it should
@@ -46,8 +46,14 @@ public LazyCacheHandler()
         {}
 
         /// <summary>
-        /// BBernard
-        /// A wrapper implementation for ICacheRepository to make working with Thread Safety significantly easier.
+        /// This overload enables dynamic self-populating cache retrieval of the results on any result generated by the specified
+        /// cache item/result factory Func&lt;T&gt;. Using the Cache Item Expiration Policy provided the cache will ensure that
+        /// the work is only ever performed by one and only one request, whereby all other simultaneous requests will immediately
+        /// benefit from the work and receive the cached item once it's generated.
+        /// 
+        /// In this overload the CacheItem policy is known before executing the logic so it is consistent for all calls to this method.
+        /// 
+        /// Ultimately this is a wrapper implementation for ICacheRepository to make working with Thread Safety significantly easier.
         /// This provides completely ThreadSafe cache with Lazy Loading capabilities in an easy to use function; 
         /// Lazy<typeparamref name="TValue"/> loading facilitates self-populating cache so that the long running processes are never 
         /// executed more than once, even if they are triggered at approx. the same time.
@@ -59,11 +65,11 @@ public LazyCacheHandler()
         /// https://blog.falafel.com/working-system-runtime-caching-memorycache/
         /// </summary>
         /// <typeparam name="TKey"></typeparam>
-        /// <typeparam name="T"></typeparam>
         /// <param name="key"></param>
         /// <param name="fnValueFactory"></param>
         /// <param name="cacheItemPolicy"></param>
         /// <returns></returns>
+        /// <exception cref="ArgumentNullException"></exception>
         public virtual TValue GetOrAddFromCache<TKey>(TKey key, Func<TValue> fnValueFactory, CacheItemPolicy cacheItemPolicy)
         {
             //We support either ILazyCacheKey interface or any object for the Cache Key as long as it's ToString() 
@@ -99,9 +105,54 @@ public virtual TValue GetOrAddFromCache<TKey>(TKey key, Func<TValue> fnValueFact
         }
 
         /// <summary>
-        /// BBernard
+        /// This overload enables dynamic self-populating cache retrieval whereby the actual cache item logic also returns
+        /// the cache expiration policy in addition to the cache item result.  This is very useful in cases such as Auth tokens,
+        /// and external API calls whereby the response contains information about how long the data returned is valid. And therefore
+        /// the response can be used to construct a highly optimized Cache Expiration Policy based on the data returned -- rather than
+        /// simply guessing and/or hard coding how long the data is valid for.
+        /// </summary>
+        /// <typeparam name="TKey"></typeparam>
+        /// <param name="key"></param>
+        /// <param name="fnValueFactory"></param>
+        /// <returns></returns>
+        /// <exception cref="ArgumentNullException"></exception>
+        public TValue GetOrAddFromCache<TKey>(TKey key, Func<ILazySelfExpiringCacheResult<TValue>> fnValueFactory)
+        {
+            if (fnValueFactory == null)
+                throw new ArgumentNullException(nameof(fnValueFactory));
+
+            //TODO: WIP: TEST THAT this REF Approach works...
+            CacheItemPolicy cacheItemPolicyFromResultRef = null;
+            return GetOrAddFromCache(key, () =>
+                {
+                    //Execute the original Cache Factory method... 
+                    var selfExpiringCacheResult = fnValueFactory.Invoke();
+                    //Now unwrap the results and set our CacheItemPolicy Reference from the result into our captured ref...
+                    cacheItemPolicyFromResultRef = selfExpiringCacheResult.CachePolicy;
+
+                    //Validate that the returned policy is valid; otherwise we used a Disabled Cache Policy fallback to ensure
+                    //  that the code still runs without issue...
+                    if (!LazyCachePolicy.IsPolicyEnabled(cacheItemPolicyFromResultRef))
+                        cacheItemPolicyFromResultRef = LazyCachePolicy.DisabledCachingPolicy;
+
+                    //Finally return the actual result just as a normal cache item factory would...
+                    return selfExpiringCacheResult.CacheItem;
+                },
+                //Here we pass in our Ref that will be dynamically updated by the cache item factory if it executes,
+                //  otherwise this will not be used since the value is loaded from the cache...
+                cacheItemPolicyFromResultRef
+            );
+        }
+
+        /// <summary>
+        /// This overload enables async dynamic self-populating cache retrieval of the results on any result generated by the specified
+        /// cache item/result factory Func&lt;T&gt;. Using the Cache Item Expiration Policy provided the cache will ensure that
+        /// the work is only ever performed by one and only one request, whereby all other simultaneous requests will immediately
+        /// benefit from the work and receive the cached item once it's generated.
         /// 
-        /// An Async wrapper implementation for using ICacheRepository to make working with Thread Safety for 
+        /// In this overload the CacheItem policy is known before executing the logic so it is consistent for all calls to this method.
+        /// 
+        /// Ultimately this is an Async wrapper implementation for using ICacheRepository to make working with Thread Safety for 
         /// Asynchronous processes significantly easier. This provides completely ThreadSafe Async cache with Lazy Loading capabilities 
         /// in an easy to use function; Lazy<typeparamref name="TValue"/> loading facilitates self-populating cache so that the long running processes are never 
         /// executed more than once, even if they are triggered at approx. the same time.
@@ -123,14 +174,18 @@ public virtual TValue GetOrAddFromCache<TKey>(TKey key, Func<TValue> fnValueFact
         ///         the Async/Await Task Based Asynchronous pattern from top to bottom and even with our caching!
         /// 
         /// </summary>
-        /// <typeparam name="T"></typeparam>
+        /// <typeparam name="TKey"></typeparam>
         /// <param name="key"></param>
         /// <param name="fnAsyncValueFactory"></param>
         /// <param name="cacheItemPolicy"></param>
         /// <returns></returns>
+        /// <exception cref="ArgumentNullException"></exception>
         public virtual async Task<TValue> GetOrAddFromCacheAsync<TKey>(TKey key, Func<Task<TValue>> fnAsyncValueFactory, CacheItemPolicy cacheItemPolicy)
         {
-            //We support eitehr ILazyCacheKey interface or any object for the Cache Key as long as it's ToString() 
+            if (fnAsyncValueFactory == null)
+                throw new ArgumentNullException(nameof(fnAsyncValueFactory));
+
+            //We support either ILazyCacheKey interface or any object for the Cache Key as long as it's ToString() 
             //  implementation creates a valid unique Key for us, so here we initialize the Cache Key to use.
             string cacheKey = GenerateCacheKeyHelper(key);
 
@@ -179,6 +234,46 @@ public virtual async Task<TValue> GetOrAddFromCacheAsync<TKey>(TKey key, Func<Ta
             }
         }
 
+        /// <summary>
+        /// This overload enables async dynamic self-populating cache retrieval whereby the actual cache item logic also returns
+        /// the cache expiration policy in addition to the cache item result.  This is very useful in cases such as Auth tokens,
+        /// and external API calls whereby the response contains information about how long the data returned is valid. And therefore
+        /// the response can be used to construct a highly optimized Cache Expiration Policy based on the data returned -- rather than
+        /// simply guessing and/or hard coding how long the data is valid for.
+        /// </summary>
+        /// <typeparam name="TKey"></typeparam>
+        /// <param name="key"></param>
+        /// <param name="fnAsyncValueFactory"></param>
+        /// <returns></returns>
+        /// <exception cref="ArgumentNullException"></exception>
+        public Task<TValue> GetOrAddFromCacheAsync<TKey>(TKey key, Func<Task<ILazySelfExpiringCacheResult<TValue>>> fnAsyncValueFactory)
+        {
+            if (fnAsyncValueFactory == null)
+                throw new ArgumentNullException(nameof(fnAsyncValueFactory));
+
+            //TODO: WIP: TEST THAT this REF Approach works...
+            CacheItemPolicy cacheItemPolicyFromResultRef = null;
+            return GetOrAddFromCacheAsync(key, async () =>
+                {
+                    //Execute the original Cache Factory method... 
+                    var selfExpiringCacheResult = await fnAsyncValueFactory.Invoke();
+                    //Now unwrap the results and set our CacheItemPolicy Reference from the result into our captured ref...
+                    cacheItemPolicyFromResultRef = selfExpiringCacheResult.CachePolicy;
+                    
+                    //Validate that the returned policy is valid; otherwise we used a Disabled Cache Policy fallback to ensure
+                    //  that the code still runs without issue...
+                    if (!LazyCachePolicy.IsPolicyEnabled(cacheItemPolicyFromResultRef))
+                        cacheItemPolicyFromResultRef = LazyCachePolicy.DisabledCachingPolicy;
+
+                    //Finally return the actual result just as a normal cache item factory would...
+                    return selfExpiringCacheResult.CacheItem;
+                },
+                //Here we pass in our Ref that will be dynamically updated by the cache item factory if it executes,
+                //  otherwise this will not be used since the value is loaded from the cache...
+                cacheItemPolicyFromResultRef
+            );
+        }
+
         /// <summary>
         /// BBernard
         /// 
@@ -232,6 +327,5 @@ protected virtual string GenerateCacheKeyHelper<TKey>(TKey cacheKeyGenerator)
         }
 
         #endregion
-
     }
 }