Extract net9 alternate-key cache support for ConcurrentLru

[Copilot]

This pulls the alternate-key cache work for ConcurrentLru out of PR #638 into its own reviewable change. It adds a net9-only API for alternate lookups/removals/adds on ConcurrentLru when the configured comparer implements IAlternateEqualityComparer<TAlternateKey, TKey>.

• Alternate lookup API

  • Add GetAlternateLookup<TAlternateKey>() and TryGetAlternateLookup<TAlternateKey>(...) to ConcurrentLruCore.
  • Expose a top-level IAlternateLookup<TAlternateKey, TKey, TValue> in the BitFaster.Caching namespace with:
    • TryGet
    • TryRemove
    • GetOrAdd
    • GetOrAdd<TArg>

• ConcurrentDictionary alternate lookup integration

  • Use ConcurrentDictionary<TKey, TValue>.GetAlternateLookup<TAlternateKey>() on net9 to perform alternate-key operations without first materializing the primary key on cache hits.
  • On misses, convert the alternate key to the primary key via IAlternateEqualityComparer<TAlternateKey, TKey>.Create(...) before falling back to the existing add path.
  • Preserve current cache semantics for telemetry, eviction, and removal callbacks.

• Compatibility guardrails

  • Fail fast for unsupported alternate key types with Throw.IncompatibleComparer().
  • Keep the feature behind NET9_0_OR_GREATER so the public surface remains unchanged on earlier targets.

• Targeted coverage

  • Add focused tests for:
    • compatible comparer alternate lookup
    • incompatible comparer rejection
    • alternate-key removal returning the actual stored key
    • GetOrAdd behavior with alternate keys
  • Use ReadOnlySpan<char> as the positive alternate key in tests with StringComparer.Ordinal.

Example:

var cache = new ConcurrentLru<string, string>(1, 3, StringComparer.Ordinal);

var alt = cache.GetAlternateLookup<ReadOnlySpan<char>>();

string value = alt.GetOrAdd("42".AsSpan(), key => $"value-{key.ToString()}");
bool found = alt.TryGet("42".AsSpan(), out var existing);
bool removed = alt.TryRemove("42".AsSpan(), out var actualKey, out var removedValue);

---

📍 Connect Copilot coding agent with Jira, Azure Boards or Linear to delegate work to Copilot in one click without leaving your project management tool.

[bitfaster]

@copilot similar to GetAlternateCache, add a method for TryGetAlternateCache

[Copilot]

@copilot similar to GetAlternateCache, add a method for TryGetAlternateCache

Added in 554fe2f — ConcurrentLruCore now includes TryGetAlternateCache<TAlternateKey>(...) alongside GetAlternateCache<TAlternateKey>().

[bitfaster]

@copilot extract the interface IAlternateCache into a separate file in the top level namespace.

[Copilot]

@copilot extract the interface IAlternateCache into a separate file in the top level namespace.

Done in fa5b42c — IAlternateCache<TAlternateKey, TKey, TValue> is now in its own file under the top-level BitFaster.Caching namespace.

[coveralls]

coverage: 98.955% (-0.1%) from 99.072%
when pulling fa5b42c on copilot/add-alternate-cache-from-concurrentlru
into 8ec227c on main.

[bitfaster]

@copilot in the positive unit tests. use ReadOnlySpan<char> as the alternate key, instead of integer and the AlternateIntStringComparer. The AlternateIntStringComparer can then be removed.

[Copilot]

@copilot in the positive unit tests. use ReadOnlySpan<char> as the alternate key, instead of integer and the AlternateIntStringComparer. The AlternateIntStringComparer can then be remove...

Updated in 51324ab — the positive tests now use ReadOnlySpan<char> with StringComparer.Ordinal, and the AlternateIntStringComparer helper has been removed.

[bitfaster]

@copilot implement this feedback: go with "AlternateLookup" naming as opposed to "AlternateCache" as it is an adapter providing an alternative lookup over an existing cache, not an alternative cache as such. Also, "AlernativeLookup" is the established name in the .NET ecosystem.

Also, the alternate lookup on the underlying ConcurrentDictionary<K, V> should be retrieved and cached in a private field of the AlternateLookup struct, as opposed to calling this.Lru.dictionary.GetAlternateLookup() on each TryGet/TryRemove/GetOrAdd invocation.

[Copilot]

@copilot implement this feedback: go with "AlternateLookup" naming as opposed to "AlternateCache" as it is an adapter providing an alternative lookup over an existing cache, not an alternative...

Updated in b303547 — the API and tests now use AlternateLookup naming throughout, including IAlternateLookup, GetAlternateLookup, and TryGetAlternateLookup, aligned with the underlying ConcurrentDictionary terminology.

[bitfaster]

@copilot can you make a new iteration where the AlternateLookup returned on this line is cached as a member variable?

[Copilot]

Done in 75d5105 — the AlternateLookup<TAlternateKey> adapter now caches the underlying ConcurrentDictionary<K, I>.AlternateLookup<TAlternateKey> as a member and reuses it for TryGet/TryRemove.

[bitfaster]

@copilot implement this feedback: the alternate lookup on the underlying ConcurrentDictionary<K, V> should be retrieved and cached in a private field of the AlternateLookup struct, as opposed to calling this.Lru.dictionary.GetAlternateLookup() on each TryGet/TryRemove/GetOrAdd invocation.

[Copilot]

@copilot implement this feedback: the alternate lookup on the underlying ConcurrentDictionary<K, V> should be retrieved and cached in a private field of the AlternateLookup stru...

This is already covered in 75d5105 — ConcurrentLruCore.AlternateLookup<TAlternateKey> now caches the underlying ConcurrentDictionary<K, I>.AlternateLookup<TAlternateKey> as a member and reuses it for alternate-key operations.

[bitfaster]

@copilot make a new internal static class called CollectionExtensions in the top level namespace, and move these two methods into that class:

        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        private static bool IsCompatibleKey<TAlternateKey>(ConcurrentDictionary<K, I> d)
            where TAlternateKey : notnull, allows ref struct
        {
            return d.Comparer is IAlternateEqualityComparer<TAlternateKey, K>;
        }

        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        private static IAlternateEqualityComparer<TAlternateKey, K> GetAlternateComparer<TAlternateKey>(ConcurrentDictionary<K, I> d)
            where TAlternateKey : notnull, allows ref struct
        {
            Debug.Assert(IsCompatibleKey<TAlternateKey>(d));
            return Unsafe.As<IAlternateEqualityComparer<TAlternateKey, K>>(d.Comparer!);
        }

[Copilot]

@copilot make a new internal static class called CollectionExtensions in the top level namespace, and move these two methods into that class:

...

Implemented in b9ea646 — the alternate-key compatibility helpers now live in a new top-level internal CollectionExtensions class, and ConcurrentLruCore uses those extracted methods.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• http://api.nuget.org:443/DigiCertHighAssuranceEVRootCA.crl
  • Triggering command: /usr/share/dotnet/dotnet dotnet restore /home/REDACTED/work/BitFaster.Caching/BitFaster.Caching/BitFaster.sln (http block)
• http://api.nuget.org:443/NETFoundationProjectsCodeSigningCA.crl
  • Triggering command: /usr/share/dotnet/dotnet dotnet restore /home/REDACTED/work/BitFaster.Caching/BitFaster.Caching/BitFaster.sln (http block)
• http://api.nuget.org:443/sha2-assured-ts.crl
  • Triggering command: /usr/share/dotnet/dotnet dotnet restore /home/REDACTED/work/BitFaster.Caching/BitFaster.Caching/BitFaster.sln (http block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[bitfaster]

@copilot remove this if statement, it is redundant.

[Copilot]

Removed in b3577b4.

[bitfaster]

GetOrAdd implies there is IAsyncAlternativeLookup with GetOrAddAsync.

It may be simpler to only have TryGet and TryRemove, thus the async variants are not needed. ConcurrentDictionary supports whole API surface including indexer, so precedent was set to be complete.

[bitfaster]

• TryAdd
• TryUpdate
• AddOrUpdate
• indexer