Add IAsyncCacheExt for .NET Standard (#572)

Author: bitfaster

BitFaster.Caching/IAsyncCacheExt.cs

@@ -0,0 +1,49 @@
+using System;
+using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
+using System.Threading.Tasks;
+
+namespace BitFaster.Caching
+{
+    /// <summary>
+    /// Represents a generic cache of key/value pairs.
+    /// </summary>
+    /// <typeparam name="K">The type of keys in the cache.</typeparam>
+    /// <typeparam name="V">The type of values in the cache.</typeparam>
+    /// <remarks>This interface enables .NET Standard to use cache methods added to IAsyncCache since v2.0. It will be removed in the next major version.</remarks>
+    public interface IAsyncCacheExt<K, V> : IAsyncCache<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.
+// backcompat: remove conditional compile
+#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 asynchronously generate a value for the key.</param>
+        /// <param name="factoryArgument">An argument value to pass into valueFactory.</param>
+        /// <returns>A task that represents the asynchronous GetOrAdd operation.</returns>
+        /// <remarks>The default implementation given here is the fallback that provides backwards compatibility for classes that implement ICache on prior versions</remarks>
+        ValueTask<V> GetOrAddAsync<TArg>(K key, Func<K, TArg, Task<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/ICacheExt.cs

@@ -9,11 +9,13 @@ namespace BitFaster.Caching
     /// </summary>
     /// <typeparam name="K">The type of keys in the cache.</typeparam>
     /// <typeparam name="V">The type of values in the cache.</typeparam>
+    /// <remarks>This interface enables .NET Standard to use cache methods added to ICache since v2.0. It will be removed in the next major version.</remarks>
     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.
+// backcompat: remove conditional compile
 #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 

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> : ICacheExt<K, V>, IAsyncCache<K, V>, IBoundedPolicy
+    public sealed class ConcurrentLfu<K, V> : ICacheExt<K, V>, IAsyncCacheExt<K, V>, IBoundedPolicy
         where K : notnull
     {
         // Note: for performance reasons this is a mutable struct, it cannot be readonly.

BitFaster.Caching/Lfu/ConcurrentTLfu.cs

@@ -9,7 +9,7 @@
 namespace BitFaster.Caching.Lfu
 {
     // LFU with time-based expiry policy. Provided as a wrapper around ConcurrentLfuCore to hide generic item and policy.
-    internal sealed class ConcurrentTLfu<K, V> : ICacheExt<K, V>, IAsyncCache<K, V>, IBoundedPolicy, ITimePolicy, IDiscreteTimePolicy
+    internal sealed class ConcurrentTLfu<K, V> : ICacheExt<K, V>, IAsyncCacheExt<K, V>, IBoundedPolicy, ITimePolicy, IDiscreteTimePolicy
         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> : ICacheExt<K, V>, IAsyncCache<K, V>, IBoundedPolicy, IEnumerable<KeyValuePair<K, V>>
+    public sealed class ClassicLru<K, V> : ICacheExt<K, V>, IAsyncCacheExt<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> : ICacheExt<K, V>, IAsyncCache<K, V>, IEnumerable<KeyValuePair<K, V>>
+    public class ConcurrentLruCore<K, V, I, P, T> : ICacheExt<K, V>, IAsyncCacheExt<K, V>, IEnumerable<KeyValuePair<K, V>>
         where K : notnull
         where I : LruItem<K, V>
         where P : struct, IItemPolicy<K, V, I>