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, updates, and add-or-get/update flows 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
    • TryUpdate
    • AddOrUpdate
    • 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.
  • Cache the underlying ConcurrentDictionary alternate lookup adapter for repeated alternate-key operations.
  • Centralize the shared value-update logic so both primary-key and alternate-key TryUpdate paths preserve the same update semantics.
  • Cache the converted primary key across AddOrUpdate retries to avoid repeated alternate-key materialization under contention.
  • On misses, convert the alternate key to the primary key via IAlternateEqualityComparer<TAlternateKey, TKey>.Create(...) before falling back to the existing add/update paths.
  • Preserve current cache semantics for telemetry, eviction, update notifications, disposal, 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
    • TryUpdate behavior with alternate keys
    • AddOrUpdate behavior with alternate keys
    • 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()}");
alt.AddOrUpdate("42".AsSpan(), "updated");
bool updated = alt.TryUpdate("42".AsSpan(), "updated-again");
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.927% (-0.06%) from 98.99%
when pulling 07526ab on copilot/add-alternate-cache-from-concurrentlru
into fc6739c 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]

• TryAdd
• AddOrUpdate

[bitfaster]

@copilot add TryAdd and AddOrUpdate and implement them for ConcurrentLruCore. Add tests to verify they function correctly.

[Copilot]

Added in 3e40ba9.

[bitfaster]

@copilot change this to TryUpdate

[Copilot]

Changed in 64275ae.

[bitfaster]

@copilot delete the TryAdd method because it is not part of ICache. Remove it from IAlternateLookup and also remove the associated tests.

[Copilot]

Implemented in 5420437.

[bitfaster]

@copilot implement AddOrUpdate as part of AlternateLookup. Add this new method to the IAlternateLookup interface and provide unit tests.

[Copilot]

Implemented in 023c085.