Add new interface to expose 3 new methods without breaking existing clients (#566)

* Add ICache2 and implement it in ConcurrentLruCore to expose 3 new methods without breaking existing clients

* a

* a

* Rename ICache2 to ICacheExt

* Rename File

* Add comment

---------

Author: wangzq

BitFaster.Caching.UnitTests/Lru/CacheExtTests.cs

@@ -0,0 +1,52 @@
+using System;
+using System.Linq;
+using BitFaster.Caching.Lfu;
+using BitFaster.Caching.Lru;
+using FluentAssertions;
+using Xunit;
+
+namespace BitFaster.Caching.UnitTests.Lru
+{
+    public class CacheExtTests
+    {
+        [Fact]
+        public void CanUseICache2FromClassicLru()
+        {
+            var cache = new ClassicLru<int, string>(5);
+            var cache2 = (ICacheExt<int, string>)cache;
+            cache2.GetOrAdd(42, static (k, i) => (k + i).ToString(), 1).Should().Be("43");
+            cache2.TryRemove(43, out _).Should().BeFalse();
+            var first = cache2.First();
+            cache2.TryRemove(first).Should().BeTrue();
+        }
+
+        [Fact]
+        public void CanUseICache2FromConcurrentLfuBuilder()
+        {
+            var cache = new ConcurrentLfuBuilder<int, string>()
+                .WithCapacity(5)
+                .Build();
+            
+            var cache2 = (ICacheExt<int, string>)cache;
+            cache2.GetOrAdd(42, static (k, i) => (k + i).ToString(), 1).Should().Be("43");
+            cache2.TryRemove(43, out _).Should().BeFalse();
+            var first = cache2.First();
+            cache2.TryRemove(first).Should().BeTrue();
+        }
+
+        [Fact]
+        public void CanUseICache2FromConcurrentLruBuilder()
+        {
+            var cache = new ConcurrentLruBuilder<int, string>()
+                .WithCapacity(5)
+                .WithExpireAfterAccess(TimeSpan.FromSeconds(5))
+                .Build();
+            
+            var cache2 = (ICacheExt<int, string>)cache;
+            cache2.GetOrAdd(42, static (k, i) => (k + i).ToString(), 1).Should().Be("43");
+            cache2.TryRemove(43, out _).Should().BeFalse();
+            var first = cache2.First();
+            cache2.TryRemove(first).Should().BeTrue();
+        }
+    }
+}

BitFaster.Caching/ICacheExt.cs

@@ -0,0 +1,46 @@
+using System;
+using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
+
+namespace BitFaster.Caching
+{
+    /// <summary>
+    /// Represents a generic cache of key/value pairs. This is a new interface with new methods to avoid breaking backward compatibility.
+    /// </summary>
+    /// <typeparam name="K">The type of keys in the cache.</typeparam>
+    /// <typeparam name="V">The type of values in the cache.</typeparam>
+    public interface ICacheExt<K, V> : ICache<K, V>
+    {
+        // Following methods were also defined in ICache with default interface implementation which only works for
+        // certain build targets, for other build targets we will define them within this new interface to avoid breaking
+        // existing clients.
+#if !NETCOREAPP3_0_OR_GREATER
+        /// <summary>
+        /// Adds a key/value pair to the cache if the key does not already exist. Returns the new value, or the 
+        /// existing value if the key already exists.
+        /// </summary>
+        /// <typeparam name="TArg">The type of an argument to pass into valueFactory.</typeparam>
+        /// <param name="key">The key of the element to add.</param>
+        /// <param name="valueFactory">The factory function used to generate a value for the key.</param>
+        /// <param name="factoryArgument">An argument value to pass into valueFactory.</param>
+        /// <returns>The value for the key. This will be either the existing value for the key if the key is already 
+        /// in the cache, or the new value if the key was not in the cache.</returns>
+        V GetOrAdd<TArg>(K key, Func<K, TArg, V> valueFactory, TArg factoryArgument);
+
+        /// <summary>
+        /// Attempts to remove and return the value that has the specified key.
+        /// </summary>
+        /// <param name="key">The key of the element to remove.</param>
+        /// <param name="value">When this method returns, contains the object removed, or the default value of the value type if key does not exist.</param>
+        /// <returns>true if the object was removed successfully; otherwise, false.</returns>
+        bool TryRemove(K key, [MaybeNullWhen(false)] out V value);
+
+        /// <summary>
+        /// Attempts to remove the specified key value pair.
+        /// </summary>
+        /// <param name="item">The item to remove.</param>
+        /// <returns>true if the item was removed successfully; otherwise, false.</returns>
+        bool TryRemove(KeyValuePair<K, V> item);
+#endif
+    }
+}

BitFaster.Caching/Lfu/ConcurrentLfu.cs

@@ -32,7 +32,7 @@ namespace BitFaster.Caching.Lfu
     /// https://github.com/ben-manes/caffeine
     [DebuggerTypeProxy(typeof(ConcurrentLfu<,>.LfuDebugView<>))]
     [DebuggerDisplay("Count = {Count}/{Capacity}")]
-    public sealed class ConcurrentLfu<K, V> : ICache<K, V>, IAsyncCache<K, V>, IBoundedPolicy
+    public sealed class ConcurrentLfu<K, V> : ICacheExt<K, V>, IAsyncCache<K, V>, IBoundedPolicy
         where K : notnull
     {
         // Note: for performance reasons this is a mutable struct, it cannot be readonly.

BitFaster.Caching/Lru/ClassicLru.cs

@@ -18,7 +18,7 @@ namespace BitFaster.Caching.Lru
     /// </remarks>
     /// <typeparam name="K">The type of the key</typeparam>
     /// <typeparam name="V">The type of the value</typeparam>
-    public sealed class ClassicLru<K, V> : ICache<K, V>, IAsyncCache<K, V>, IBoundedPolicy, IEnumerable<KeyValuePair<K, V>>
+    public sealed class ClassicLru<K, V> : ICacheExt<K, V>, IAsyncCache<K, V>, IBoundedPolicy, IEnumerable<KeyValuePair<K, V>>
         where K : notnull
     {
         private readonly int capacity;

BitFaster.Caching/Lru/ConcurrentLruCore.cs

@@ -32,7 +32,7 @@ namespace BitFaster.Caching.Lru
     ///   <item><description>When cold is full, cold tail is moved to warm head or removed from dictionary on depending on WasAccessed.</description></item>
     ///</list>
     /// </remarks>
-    public class ConcurrentLruCore<K, V, I, P, T> : ICache<K, V>, IAsyncCache<K, V>, IEnumerable<KeyValuePair<K, V>>
+    public class ConcurrentLruCore<K, V, I, P, T> : ICacheExt<K, V>, IAsyncCache<K, V>, IEnumerable<KeyValuePair<K, V>>
         where K : notnull
         where I : LruItem<K, V>
         where P : struct, IItemPolicy<K, V, I>