Added cache time-to-live and overloads. Further code documentation.

FastMemoryCache/ItemToRemove.cs

@@ -0,0 +1,22 @@
+namespace NTDLS.FastMemoryCache
+{
+    internal class ItemToRemove
+    {
+        public string Key { get; set; }
+        public int AproximateSizeInBytes { get; set; }
+        public bool Expired { get; set; }
+
+        public ItemToRemove(string key, int aproximateSizeInBytes)
+        {
+            Key = key;
+            AproximateSizeInBytes = aproximateSizeInBytes;
+        }
+
+        public ItemToRemove(string key, int aproximateSizeInBytes, bool expired)
+        {
+            Key = key;
+            AproximateSizeInBytes = aproximateSizeInBytes;
+            Expired = expired;
+        }
+    }
+}

FastMemoryCache/Metrics/CachePartitionAllocationDetails.cs

@@ -32,7 +32,7 @@ public class CachePartitionAllocationDetailItem
             /// <summary>
             /// Instanciates a new instance of the detail metric.
             /// </summary>
-            /// <param name="key"></param>
+            /// <param name="key">The unique cache key used to identify the item.</param>
             public CachePartitionAllocationDetailItem(string key)
             {
                 Key = key;

FastMemoryCache/NTDLS.FastMemoryCache.csproj

@@ -13,15 +13,15 @@
     <RepositoryUrl>https://github.com/NTDLS/NTDLS.FastMemoryCache</RepositoryUrl>
     <PackageTags>memory-cache;partitioned-cache;managed-cache;fast-cache;cache;memory</PackageTags>
     <PackageReleaseNotes>
-      Added .net8
+      Added cache time-to-live and overloads. Further code documentation.
     </PackageReleaseNotes>
     <RepositoryType>git</RepositoryType>
     <PackageLicenseExpression>Apache-2.0</PackageLicenseExpression>
     <Authors>NetworkDLS</Authors>
     <Company>NetworkDLS</Company>
-    <AssemblyVersion>1.4.4</AssemblyVersion>
-    <FileVersion>1.4.4</FileVersion>
-    <VersionPrefix>1.4.4</VersionPrefix>
+    <AssemblyVersion>1.5.0</AssemblyVersion>
+    <FileVersion>1.5.0</FileVersion>
+    <VersionPrefix>1.5.0</VersionPrefix>
     <version></version>
     <PackageReadmeFile>README.md</PackageReadmeFile>
     <PackageIcon>64.png</PackageIcon>

FastMemoryCache/PartitionedMemoryCache.cs

@@ -18,7 +18,6 @@ public class PartitionedMemoryCache : IDisposable
         /// </summary>
         public PartitionedCacheConfiguration Configuration => _configuration.Clone();
 
-
         #region Ctor.
 
         /// <summary>
@@ -265,7 +264,7 @@ public CachePartitionAllocationDetails GetPartitionAllocationDetails()
         /// <summary>
         /// Determines if any of the cache partitons contain a cache item with the supplied key value.
         /// </summary>
-        /// <param name="key"></param>
+        /// <param name="key">The unique cache key used to identify the item.</param>
         /// <returns></returns>
         public bool Contains(string key)
         {
@@ -290,7 +289,7 @@ public bool Contains(string key)
         /// <summary>
         /// Gets the cache item with the supplied key value, throws an exception if it is not found.
         /// </summary>
-        /// <param name="key"></param>
+        /// <param name="key">The unique cache key used to identify the item.</param>
         /// <returns></returns>
         public object Get(string key)
         {
@@ -310,8 +309,8 @@ public object Get(string key)
         /// <summary>
         /// Gets the cache item with the supplied key value, throws an exception if it is not found.
         /// </summary>
-        /// <typeparam name="T"></typeparam>
-        /// <param name="key"></param>
+        /// <typeparam name="T">The type of the object that is stored in cache.</typeparam>
+        /// <param name="key">The unique cache key used to identify the item.</param>
         /// <returns></returns>
         public T Get<T>(string key)
         {
@@ -335,8 +334,8 @@ public T Get<T>(string key)
         /// <summary>
         /// Attempts to get the cache item with the supplied key value, returns true of found otherwise fale.
         /// </summary>
-        /// <typeparam name="T"></typeparam>
-        /// <param name="key"></param>
+        /// <typeparam name="T">The type of the object that is stored in cache.</typeparam>
+        /// <param name="key">The unique cache key used to identify the item.</param>
         /// <param name="cachedObject"></param>
         /// <returns></returns>
         public bool TryGet<T>(string key, [NotNullWhen(true)] out T? cachedObject)
@@ -357,7 +356,7 @@ public bool TryGet<T>(string key, [NotNullWhen(true)] out T? cachedObject)
         /// <summary>
         /// Attempts to get the cache item with the supplied key value, returns true of found otherwise fale.
         /// </summary>
-        /// <param name="key"></param>
+        /// <param name="key">The unique cache key used to identify the item.</param>
         /// <returns></returns>
         public object? TryGet(string key)
         {
@@ -379,12 +378,13 @@ public bool TryGet<T>(string key, [NotNullWhen(true)] out T? cachedObject)
         #region Upserters.
 
         /// <summary>
-        /// Inserts an item into the memory cache. If it alreay exists, then it will be updated. The size of the object will be estimated.
+        /// Inserts an item into the memory cache. If it alreay exists, then it will be updated.
         /// </summary>
-        /// <typeparam name="T"></typeparam>
-        /// <param name="key"></param>
-        /// <param name="value"></param>
-        public void Upsert<T>(string key, T value)
+        /// <param name="key">The unique cache key used to identify the item.</param>
+        /// <param name="value">The value to store in the cache.</param>
+        /// <param name="aproximateSizeInBytes">The aproximate size of the object in byets. If NULL, the size will estimated.</param>
+        /// <param name="timeToLive">The amount of time from insertion, update or last read that the item should live in cache. 0 = infinite.</param>
+        public void Upsert(string key, object value, int? aproximateSizeInBytes, TimeSpan? timeToLive)
         {
             if (_configuration.IsCaseSensitive == false)
             {
@@ -395,16 +395,19 @@ public void Upsert<T>(string key, T value)
 
             lock (_partitions[partitionIndex])
             {
-                _partitions[partitionIndex].Upsert<T>(key, value);
+                _partitions[partitionIndex].Upsert(key, value, aproximateSizeInBytes, timeToLive);
             }
         }
 
         /// <summary>
-        /// Inserts an item into the memory cache. If it alreay exists, then it will be updated. The size of the object will be estimated.
+        /// Inserts an item into the memory cache. If it alreay exists, then it will be updated.
         /// </summary>
-        /// <param name="key"></param>
-        /// <param name="value"></param>
-        public void Upsert(string key, object value)
+        /// <typeparam name="T">The type of the object that is stored in cache.</typeparam>
+        /// <param name="key">The unique cache key used to identify the item.</param>
+        /// <param name="value">The value to store in the cache.</param>
+        /// <param name="aproximateSizeInBytes">The aproximate size of the object in byets. If NULL, the size will estimated.</param>
+        /// <param name="timeToLive">The amount of time from insertion, update or last read that the item should live in cache. 0 = infinite.</param>
+        public void Upsert<T>(string key, T value, int? aproximateSizeInBytes, TimeSpan? timeToLive)
         {
             if (_configuration.IsCaseSensitive == false)
             {
@@ -415,52 +418,57 @@ public void Upsert(string key, object value)
 
             lock (_partitions[partitionIndex])
             {
-                _partitions[partitionIndex].Upsert(key, value);
+                _partitions[partitionIndex].Upsert<T>(key, value, aproximateSizeInBytes, timeToLive);
             }
         }
 
         /// <summary>
-        /// Inserts an item into the memory cache. If it alreay exists, then it will be updated.
+        /// Inserts an item into the memory cache. If it alreay exists, then it will be updated. The size of the object will be estimated.
         /// </summary>
-        /// <param name="key"></param>
-        /// <param name="value"></param>
-        /// <param name="aproximateSizeInBytes"></param>
-        public void Upsert(string key, object value, int aproximateSizeInBytes = 0)
-        {
-            if (_configuration.IsCaseSensitive == false)
-            {
-                key = key.ToLower();
-            }
+        /// <param name="key">The unique cache key used to identify the item.</param>
+        /// <param name="value">The value to store in the cache.</param>
+        public void Upsert<T>(string key, T value) => Upsert<T>(key, value, null, null);
 
-            int partitionIndex = Math.Abs(key.GetHashCode() % _configuration.PartitionCount);
+        /// <summary>
+        /// Inserts an item into the memory cache. If it alreay exists, then it will be updated. The size of the object will be estimated.
+        /// </summary>
+        /// <typeparam name="T">The type of the object that is stored in cache.</typeparam>
+        /// <param name="key">The unique cache key used to identify the item.</param>
+        /// <param name="value">The value to store in the cache.</param>
+        /// <param name="aproximateSizeInBytes">The aproximate size of the object in byets. If NULL, the size will estimated.</param>
+        public void Upsert<T>(string key, T value, int? aproximateSizeInBytes) => Upsert<T>(key, value, aproximateSizeInBytes, null);
 
-            lock (_partitions[partitionIndex])
-            {
-                _partitions[partitionIndex].Upsert(key, value, aproximateSizeInBytes);
-            }
-        }
+        /// <summary>
+        /// Inserts an item into the memory cache. If it alreay exists, then it will be updated. The size of the object will be estimated.
+        /// </summary>
+        /// <typeparam name="T">The type of the object that is stored in cache.</typeparam>
+        /// <param name="key">The unique cache key used to identify the item.</param>
+        /// <param name="value">The value to store in the cache.</param>
+        /// <param name="timeToLive">The amount of time from insertion, update or last read that the item should live in cache. 0 = infinite.</param>
+        public void Upsert<T>(string key, T value, TimeSpan? timeToLive) => Upsert<T>(key, value, null, timeToLive);
 
         /// <summary>
-        /// Inserts an item into the memory cache. If it alreay exists, then it will be updated.
+        /// Inserts an item into the memory cache. If it alreay exists, then it will be updated. The size of the object will be estimated.
         /// </summary>
-        /// <typeparam name="T"></typeparam>
-        /// <param name="key"></param>
-        /// <param name="value"></param>
-        /// <param name="aproximateSizeInBytes"></param>
-        public void Upsert<T>(string key, T value, int aproximateSizeInBytes = 0)
-        {
-            if (_configuration.IsCaseSensitive == false)
-            {
-                key = key.ToLower();
-            }
+        /// <param name="key">The unique cache key used to identify the item.</param>
+        /// <param name="value">The value to store in the cache.</param>
+        public void Upsert(string key, object value) => Upsert(key, value, null, null);
 
-            int partitionIndex = Math.Abs(key.GetHashCode() % _configuration.PartitionCount);
+        /// <summary>
+        /// Inserts an item into the memory cache. If it alreay exists, then it will be updated. The size of the object will be estimated.
+        /// </summary>
+        /// <param name="key">The unique cache key used to identify the item.</param>
+        /// <param name="value">The value to store in the cache.</param>
+        /// <param name="aproximateSizeInBytes">The aproximate size of the object in byets. If NULL, the size will estimated.</param>
+        public void Upsert(string key, object value, int? aproximateSizeInBytes) => Upsert(key, value, aproximateSizeInBytes, null);
 
-            lock (_partitions[partitionIndex])
-            {
-                _partitions[partitionIndex].Upsert<T>(key, value, aproximateSizeInBytes);
-            }
-        }
+        /// <summary>
+        /// Inserts an item into the memory cache. If it alreay exists, then it will be updated. The size of the object will be estimated.
+        /// </summary>
+        /// <param name="key">The unique cache key used to identify the item.</param>
+        /// <param name="value">The value to store in the cache.</param>
+        /// <param name="timeToLive">The amount of time from insertion, update or last read that the item should live in cache. 0 = infinite.</param>
+        public void Upsert(string key, object value, TimeSpan? timeToLive) => Upsert(key, value, null, timeToLive);
 
         #endregion
 
@@ -469,8 +477,8 @@ public void Upsert<T>(string key, T value, int aproximateSizeInBytes = 0)
         /// <summary>
         /// Removes an item from the cache if it is found, returns true if found and removed.
         /// </summary>
-        /// <param name="key"></param>
-        /// <returns></returns>
+        /// <param name="key">The unique cache key used to identify the item.</param>
+        /// <returns>True of the item was removed from cache.</returns>
         public bool Remove(string key)
         {
             if (_configuration.IsCaseSensitive == false)
@@ -489,21 +497,26 @@ public bool Remove(string key)
         /// <summary>
         /// Removes all itemsfrom the cache that start with the given string, returns the count of items found and removed.
         /// </summary>
-        /// <param name="prefix"></param>
-        public void RemoveItemsWithPrefix(string prefix)
+        /// <param name="prefix">The beginning of the cache key to look for when removing cache items.</param>
+        /// <returns>The number of items that were removed from cache.</returns>
+        public int RemoveItemsWithPrefix(string prefix)
         {
             if (_configuration.IsCaseSensitive == false)
             {
                 prefix = prefix.ToLower();
             }
 
+            int itemsRemoved = 0;
+
             for (int i = 0; i < _configuration.PartitionCount; i++)
             {
                 lock (_partitions[i])
                 {
-                    _partitions[i].RemoveItemsWithPrefix(prefix);
+                    itemsRemoved += _partitions[i].RemoveItemsWithPrefix(prefix);
                 }
             }
+
+            return itemsRemoved;
         }
 
         /// <summary>