Add alternate key support to ConcurrentLru

BitFaster.Caching.Benchmarks/Lru/LruJustGetOrAddAlternate.cs

@@ -0,0 +1,40 @@
+
+using System;
+using System.Collections.Generic;
+using Benchly;
+using BenchmarkDotNet.Attributes;
+using BenchmarkDotNet.Diagnosers;
+using BitFaster.Caching.Lru;
+
+namespace BitFaster.Caching.Benchmarks
+{
+    // Note: to run in VS, make .net9 the first target fmk in the .vcproj
+#if Windows
+    [DisassemblyDiagnoser(printSource: true, maxDepth: 5)]
+#endif
+    [MemoryDiagnoser(displayGenColumns: false)]
+    [HideColumns("Job", "Median", "RatioSD", "Alloc Ratio")]
+    [ColumnChart(Title = "Lookup Latency ({JOB})", Output = OutputMode.PerJob, Colors = "darkslategray,royalblue,royalblue,royalblue,royalblue,royalblue,royalblue,royalblue,#ffbf00,limegreen,indianred,indianred")]
+    public class LruJustGetOrAddAlternate
+    {
+        private static readonly ConcurrentLru<string, int> concurrentLru = new ConcurrentLru<string, int>(8, 9, EqualityComparer<string>.Default);
+
+        [Benchmark(Baseline = true)]
+        public int ConcurrentLru()
+        {
+            Func<string, int> func = x => 1;
+            return concurrentLru.GetOrAdd("foo", func);
+        }
+
+#if NET9_0_OR_GREATER
+        private static readonly IAlternateLookup<ReadOnlySpan<char>, string, int> alternate = concurrentLru.GetAlternateLookup<ReadOnlySpan<char>>();
+
+        [Benchmark()]
+        public int ConcurrentLruAlternate()
+        {
+            Func<ReadOnlySpan<char>, int> func = x => 1;
+            return alternate.GetOrAdd("foo".AsSpan(), func);
+        }
+#endif
+    }
+}

BitFaster.Caching.UnitTests/BitFaster.Caching.UnitTests.csproj

@@ -2,7 +2,8 @@
 
   <PropertyGroup>
     <TargetFrameworks>net48;netcoreapp3.1;net6.0;net9.0</TargetFrameworks>
-    <LangVersion>10.0</LangVersion>  
+    <LangVersion Condition="'$(TargetFramework)' == 'net9.0'">13.0</LangVersion>
+    <LangVersion Condition="'$(TargetFramework)' != 'net9.0'">10.0</LangVersion>
   </PropertyGroup>
 
   <ItemGroup>
@@ -30,4 +31,4 @@
     <ProjectReference Include="..\BitFaster.Caching\BitFaster.Caching.csproj" />
   </ItemGroup>
 
-</Project>
+</Project>

BitFaster.Caching.UnitTests/Lru/ConcurrentLruAlternateLookupTests.cs

@@ -0,0 +1,115 @@
+#if NET9_0_OR_GREATER
+using System;
+using BitFaster.Caching.Lru;
+using FluentAssertions;
+using Xunit;
+
+namespace BitFaster.Caching.UnitTests.Lru
+{
+    public class ConcurrentLruAlternateLookupTests
+    {
+        [Fact]
+        public void TryGetAlternateLookupReturnsLookupForCompatibleComparer()
+        {
+            var cache = new ConcurrentLru<string, string>(1, 3, StringComparer.Ordinal);
+            cache.GetOrAdd("42", _ => "value");
+            ReadOnlySpan<char> key = "42";
+
+            cache.TryGetAlternateLookup<ReadOnlySpan<char>>(out var alternate).Should().BeTrue();
+            alternate.TryGet(key, out var value).Should().BeTrue();
+            value.Should().Be("value");
+        }
+
+        [Fact]
+        public void GetAlternateLookupThrowsForIncompatibleComparer()
+        {
+            var cache = new ConcurrentLru<string, string>(1, 3, StringComparer.Ordinal);
+
+            Action act = () => cache.GetAlternateLookup<int>();
+
+            act.Should().Throw<InvalidOperationException>().WithMessage("Incompatible comparer");
+            cache.TryGetAlternateLookup<int>(out var alternate).Should().BeFalse();
+            alternate.Should().BeNull();
+        }
+
+        [Fact]
+        public void AlternateLookupTryRemoveReturnsActualKeyAndValue()
+        {
+            var cache = new ConcurrentLru<string, string>(1, 3, StringComparer.Ordinal);
+            cache.GetOrAdd("42", _ => "value");
+            var alternate = cache.GetAlternateLookup<ReadOnlySpan<char>>();
+            ReadOnlySpan<char> key = "42";
+
+            alternate.TryRemove(key, out var actualKey, out var value).Should().BeTrue();
+
+            actualKey.Should().Be("42");
+            value.Should().Be("value");
+            cache.TryGet("42", out _).Should().BeFalse();
+        }
+
+        [Fact]
+        public void AlternateLookupGetOrAddUsesAlternateKeyOnMissAndHit()
+        {
+            var cache = new ConcurrentLru<string, string>(1, 3, StringComparer.Ordinal);
+            var alternate = cache.GetAlternateLookup<ReadOnlySpan<char>>();
+            var factoryCalls = 0;
+            ReadOnlySpan<char> key = "42";
+
+            alternate.GetOrAdd(key, key =>
+            {
+                factoryCalls++;
+                return $"value-{key.ToString()}";
+            }).Should().Be("value-42");
+
+            alternate.GetOrAdd(key, (_, prefix) =>
+            {
+                factoryCalls++;
+                return prefix;
+            }, "unused").Should().Be("value-42");
+
+            factoryCalls.Should().Be(1);
+            cache.TryGet("42", out var value).Should().BeTrue();
+            value.Should().Be("value-42");
+        }
+
+        [Fact]
+        public void AlternateLookupTryUpdateReturnsFalseForMissingKeyAndUpdatesExistingValue()
+        {
+            var cache = new ConcurrentLru<string, string>(1, 3, StringComparer.Ordinal);
+            var alternate = cache.GetAlternateLookup<ReadOnlySpan<char>>();
+            ReadOnlySpan<char> key = "42";
+
+            alternate.TryUpdate(key, "value-42").Should().BeFalse();
+            cache.TryGet("42", out _).Should().BeFalse();
+
+            cache.GetOrAdd("42", _ => "value-42");
+            alternate.TryUpdate(key, "updated").Should().BeTrue();
+
+            cache.TryGet("42", out var value).Should().BeTrue();
+            value.Should().Be("updated");
+            alternate.TryGet(key, out value).Should().BeTrue();
+            value.Should().Be("updated");
+        }
+
+        [Fact]
+        public void AlternateLookupAddOrUpdateAddsMissingValueAndUpdatesExistingValue()
+        {
+            var cache = new ConcurrentLru<string, string>(1, 3, StringComparer.Ordinal);
+            var alternate = cache.GetAlternateLookup<ReadOnlySpan<char>>();
+            ReadOnlySpan<char> key = "42";
+
+            alternate.AddOrUpdate(key, "value-42");
+
+            cache.TryGet("42", out var value).Should().BeTrue();
+            value.Should().Be("value-42");
+
+            alternate.AddOrUpdate(key, "updated");
+
+            cache.TryGet("42", out value).Should().BeTrue();
+            value.Should().Be("updated");
+            alternate.TryGet(key, out value).Should().BeTrue();
+            value.Should().Be("updated");
+        }
+    }
+}
+#endif

BitFaster.Caching.UnitTests/Lru/ConcurrentLruSoakTests.cs

@@ -76,7 +76,7 @@ public async Task WhenSoakConcurrentGetWithArgCacheEndsInConsistentState()
         {
             for (int i = 0; i < 10; i++)
             {
-                await Threaded.Run(4, () =>
+                await Threaded.Run(4, () =>
                 {
                     for (int i = 0; i < 100000; i++)
                     {
@@ -94,6 +94,58 @@ await Threaded.Run(4, () =>
             }
         }
 
+#if NET9_0_OR_GREATER
+        [Fact]
+        public async Task WhenSoakConcurrentAlternateLookupGetCacheEndsInConsistentState()
+        {
+            var alternateLru = new ConcurrentLru<string, string>(1, capacity, StringComparer.Ordinal);
+            var alternate = alternateLru.GetAlternateLookup<ReadOnlySpan<char>>();
+
+            for (int i = 0; i < 10; i++)
+            {
+                await Threaded.Run(4, () =>
+                {
+                    for (int i = 0; i < 100000; i++)
+                    {
+                        string key = (i + 1).ToString();
+                        alternate.GetOrAdd(key.AsSpan(), static keySpan => keySpan.ToString());
+                    }
+                });
+
+                this.testOutputHelper.WriteLine($"{alternateLru.HotCount} {alternateLru.WarmCount} {alternateLru.ColdCount}");
+                this.testOutputHelper.WriteLine(string.Join(" ", alternateLru.Keys));
+
+                alternateLru.Count.Should().BeInRange(7, 10);
+                new ConcurrentLruIntegrityChecker<string, string, LruItem<string, string>, LruPolicy<string, string>, TelemetryPolicy<string, string>>(alternateLru).Validate();
+            }
+        }
+
+        [Fact]
+        public async Task WhenSoakConcurrentAlternateLookupGetWithArgCacheEndsInConsistentState()
+        {
+            var alternateLru = new ConcurrentLru<string, string>(1, capacity, StringComparer.Ordinal);
+            var alternate = alternateLru.GetAlternateLookup<ReadOnlySpan<char>>();
+
+            for (int i = 0; i < 10; i++)
+            {
+                await Threaded.Run(4, () =>
+                {
+                    for (int i = 0; i < 100000; i++)
+                    {
+                        string key = (i + 1).ToString();
+                        alternate.GetOrAdd(key.AsSpan(), static (keySpan, prefix) => prefix + keySpan.ToString(), "prefix-");
+                    }
+                });
+
+                this.testOutputHelper.WriteLine($"{alternateLru.HotCount} {alternateLru.WarmCount} {alternateLru.ColdCount}");
+                this.testOutputHelper.WriteLine(string.Join(" ", alternateLru.Keys));
+
+                alternateLru.Count.Should().BeInRange(7, 10);
+                new ConcurrentLruIntegrityChecker<string, string, LruItem<string, string>, LruPolicy<string, string>, TelemetryPolicy<string, string>>(alternateLru).Validate();
+            }
+        }
+#endif
+
         [Fact]
         public async Task WhenSoakConcurrentGetAsyncWithArgCacheEndsInConsistentState()
         {
@@ -122,7 +174,7 @@ public async Task WhenSoakConcurrentGetAndRemoveCacheEndsInConsistentState()
         {
             for (int i = 0; i < 10; i++)
             {
-                await Threaded.Run(4, () =>
+                await Threaded.Run(4, () =>
                 {
                     for (int i = 0; i < 100000; i++)
                     {
@@ -138,6 +190,33 @@ await Threaded.Run(4, () =>
             }
         }
 
+#if NET9_0_OR_GREATER
+        [Fact]
+        public async Task WhenSoakConcurrentAlternateLookupGetAndRemoveCacheEndsInConsistentState()
+        {
+            var alternateLru = new ConcurrentLru<string, string>(1, capacity, StringComparer.Ordinal);
+            var alternate = alternateLru.GetAlternateLookup<ReadOnlySpan<char>>();
+
+            for (int i = 0; i < 10; i++)
+            {
+                await Threaded.Run(4, () =>
+                {
+                    for (int i = 0; i < 100000; i++)
+                    {
+                        string key = (i + 1).ToString();
+                        alternate.TryRemove(key.AsSpan(), out _, out _);
+                        alternate.GetOrAdd(key.AsSpan(), static keySpan => keySpan.ToString());
+                    }
+                });
+
+                this.testOutputHelper.WriteLine($"{alternateLru.HotCount} {alternateLru.WarmCount} {alternateLru.ColdCount}");
+                this.testOutputHelper.WriteLine(string.Join(" ", alternateLru.Keys));
+
+                new ConcurrentLruIntegrityChecker<string, string, LruItem<string, string>, LruPolicy<string, string>, TelemetryPolicy<string, string>>(alternateLru).Validate();
+            }
+        }
+#endif
+
         [Fact]
         public async Task WhenSoakConcurrentGetAndRemoveKvpCacheEndsInConsistentState()
         {

BitFaster.Caching/CollectionExtensions.cs

@@ -0,0 +1,29 @@
+using System.Collections.Concurrent;
+using System.Collections.Generic;
+using System.Diagnostics;
+using System.Runtime.CompilerServices;
+
+namespace BitFaster.Caching
+{
+    internal static class CollectionExtensions
+    {
+#if NET9_0_OR_GREATER
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        internal static bool IsCompatibleKey<TAlternateKey, TKey, TValue>(this ConcurrentDictionary<TKey, TValue> dictionary)
+            where TAlternateKey : notnull, allows ref struct
+            where TKey : notnull
+        {
+            return dictionary.Comparer is IAlternateEqualityComparer<TAlternateKey, TKey>;
+        }
+
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        internal static IAlternateEqualityComparer<TAlternateKey, TKey> GetAlternateComparer<TAlternateKey, TKey, TValue>(this ConcurrentDictionary<TKey, TValue> dictionary)
+            where TAlternateKey : notnull, allows ref struct
+            where TKey : notnull
+        {
+            Debug.Assert(dictionary.IsCompatibleKey<TAlternateKey, TKey, TValue>());
+            return Unsafe.As<IAlternateEqualityComparer<TAlternateKey, TKey>>(dictionary.Comparer!);
+        }
+#endif
+    }
+}

BitFaster.Caching/IAlternateLookup.cs

@@ -0,0 +1,68 @@
+#if NET9_0_OR_GREATER
+using System;
+using System.Diagnostics.CodeAnalysis;
+
+namespace BitFaster.Caching
+{
+    /// <summary>
+    /// Provides an alternate-key lookup over a cache.
+    /// </summary>
+    /// <typeparam name="TAlternateKey">The alternate key type.</typeparam>
+    /// <typeparam name="TKey">The cache key type.</typeparam>
+    /// <typeparam name="TValue">The cache value type.</typeparam>
+    public interface IAlternateLookup<TAlternateKey, TKey, TValue>
+        where TAlternateKey : notnull, allows ref struct
+        where TKey : notnull
+    {
+        /// <summary>
+        /// Attempts to get a value using an alternate key.
+        /// </summary>
+        /// <param name="key">The alternate key.</param>
+        /// <param name="value">The cached value when found.</param>
+        /// <returns><see langword="true" /> when the key is found; otherwise, <see langword="false" />.</returns>
+        bool TryGet(TAlternateKey key, [MaybeNullWhen(false)] out TValue value);
+
+        /// <summary>
+        /// Attempts to remove a value using an alternate key.
+        /// </summary>
+        /// <param name="key">The alternate key.</param>
+        /// <param name="actualKey">The removed cache key.</param>
+        /// <param name="value">The removed value.</param>
+        /// <returns><see langword="true" /> when the key is found; otherwise, <see langword="false" />.</returns>
+        bool TryRemove(TAlternateKey key, [MaybeNullWhen(false)] out TKey actualKey, [MaybeNullWhen(false)] out TValue value);
+
+        /// <summary>
+        /// Attempts to update an existing value using an alternate key.
+        /// </summary>
+        /// <param name="key">The alternate key.</param>
+        /// <param name="value">The value to update.</param>
+        /// <returns><see langword="true" /> when the key was updated; otherwise, <see langword="false" />.</returns>
+        bool TryUpdate(TAlternateKey key, TValue value);
+
+        /// <summary>
+        /// Adds a value using an alternate key or updates the existing value.
+        /// </summary>
+        /// <param name="key">The alternate key.</param>
+        /// <param name="value">The value to add or update.</param>
+        void AddOrUpdate(TAlternateKey key, TValue value);
+
+        /// <summary>
+        /// Gets an existing value or adds a new value using an alternate key.
+        /// </summary>
+        /// <param name="key">The alternate key.</param>
+        /// <param name="valueFactory">The value factory.</param>
+        /// <returns>The cached value.</returns>
+        TValue GetOrAdd(TAlternateKey key, Func<TAlternateKey, TValue> valueFactory);
+
+        /// <summary>
+        /// Gets an existing value or adds a new value using an alternate key and factory argument.
+        /// </summary>
+        /// <typeparam name="TArg">The factory argument type.</typeparam>
+        /// <param name="key">The alternate key.</param>
+        /// <param name="valueFactory">The value factory.</param>
+        /// <param name="factoryArgument">The factory argument.</param>
+        /// <returns>The cached value.</returns>
+        TValue GetOrAdd<TArg>(TAlternateKey key, Func<TAlternateKey, TArg, TValue> valueFactory, TArg factoryArgument);
+    }
+}
+#endif