Add Equals to IHasher to eliminate virtual key comparisons

Author: Wsm2110

benchmarks/Faster.Map.Benchmark/GetBenchmark.cs

@@ -5,13 +5,12 @@
 using System.Linq;
 using BenchmarkDotNet.Engines;
 using Faster.Map.Benchmark.Utilities;
-using Faster.Map.Hasher;
 
 namespace Faster.Map.Benchmark
 {
     [MarkdownExporterAttribute.GitHub]
     [DisassemblyDiagnoser]
-    //[MemoryDiagnoser]
+    [MemoryDiagnoser]
     [SimpleJob(RunStrategy.Monitoring, launchCount: 1, iterationCount: 50, warmupCount: 3)]
 
     public class GetBenchmark

src/BlitzMap.cs

@@ -1,3 +1,4 @@
+using Faster.Map.Contracts;
 using Faster.Map.Hasher;
 using System;
 using System.Collections;
@@ -102,8 +103,7 @@ public IEnumerator<Entry> GetEnumerator()
     private uint _maxCountBeforeResize;
     private THasher _hasher;
     private uint _lastBucket = INACTIVE;
-    private EqualityComparer<TKey> _eq = EqualityComparer<TKey>.Default;
-
+   
     #endregion
     /// <summary>
     /// Initializes a new instance of the <see cref="BlitzMap{TKey, TValue, THasher}"/> class
@@ -190,7 +190,7 @@ public bool Get(TKey key, out TValue value)
                 var entry = Unsafe.Add(ref entryBase, bucket.Signature & _mask);
 
                 // Verify that the key matches using the equality comparer
-                if (_eq.Equals(key, entry.Key))
+                if (_hasher.Equals(key, entry.Key))
                 {
                     value = entry.Value; // Set the output value
                     return true; // Key found, return success
@@ -239,7 +239,7 @@ public bool Contains(TKey key)
                 // Retrieve the entry associated with the current bucket
                 var entry = Unsafe.Add(ref entryBase, bucket.Signature & _mask);
                 // Verify that the key matches using the equality comparer
-                if (_eq.Equals(key, entry.Key))
+                if (_hasher.Equals(key, entry.Key))
                 {
                     return true; // Key found, return success
                 }
@@ -287,7 +287,7 @@ public bool Update(TKey key, TValue value)
                 ref var entry = ref Unsafe.Add(ref entryBase, bucket.Signature & _mask);
 
                 // Verify that the key matches using the equality comparer
-                if (_eq.Equals(key, entry.Key))
+                if (_hasher.Equals(key, entry.Key))
                 {
                     entry.Value = value; // Update the value
                     return true;
@@ -350,7 +350,7 @@ public bool Insert(TKey key, TValue value)
 
         // Check if the current bucket already contains the key
         if (signature == (bucket.Signature & ~_mask) &&
-            _eq.Equals(key, Unsafe.Add(ref entryBase, bucket.Signature & _mask).Key))
+            _hasher.Equals(key, Unsafe.Add(ref entryBase, bucket.Signature & _mask).Key))
         {
             return false; // Key already exists, insertion fails
         }
@@ -383,7 +383,7 @@ public bool Insert(TKey key, TValue value)
 
             // Check for an existing key in the chain
             if (signature == (bucket.Signature & ~_mask) &&
-                _eq.Equals(key, _entries[bucket.Signature & _mask].Key))
+                _hasher.Equals(key, _entries[bucket.Signature & _mask].Key))
             {
                 return false; // Key already exists, insertion fails
             }
@@ -550,7 +550,7 @@ public bool InsertOrUpdate(TKey key, TValue value)
         else if (signature == (bucket.Signature & ~_mask))
         {
             ref var entry = ref Unsafe.Add(ref entryBase, bucket.Signature & _mask);
-            if (_eq.Equals(key, entry.Key))
+            if (_hasher.Equals(key, entry.Key))
             {
                 entry.Value = value;
                 return true; // Key already exists, update value
@@ -566,7 +566,7 @@ public bool InsertOrUpdate(TKey key, TValue value)
             if (signature == (bucket.Signature & ~_mask))
             {
                 ref var entry = ref Unsafe.Add(ref entryBase, bucket.Signature & _mask);
-                if (_eq.Equals(key, entry.Key))
+                if (_hasher.Equals(key, entry.Key))
                 {
                     entry.Value = value;
                     return true; // Key already exists, update value
@@ -624,7 +624,7 @@ public bool Remove(TKey key)
                 uint entryIndex = bucket.Signature & _mask;
                 ref var entry = ref Unsafe.Add(ref entryBase, entryIndex);
 
-                if (_eq.Equals(key, entry.Key))
+                if (_hasher.Equals(key, entry.Key))
                 {
                     // --- unlink bucket from chain ---
                     if (prevIndex == INACTIVE)

src/Contracts/IHasher.cs

@@ -1,11 +1,69 @@
-using System.Runtime.CompilerServices;
+using System.Collections.Generic;
+using System.Runtime.CompilerServices;
 
-namespace Faster.Map.Contracts
+namespace Faster.Map.Contracts;
+
+/// <summary>
+/// Defines a high-performance hashing and equality strategy for <c>BlitzMap</c>.
+///
+/// Implementations are intended to be <see langword="struct"/>s and supplied as generic
+/// type parameters in order to enable full static dispatch, aggressive inlining, and
+/// elimination of interface and virtual-call overhead in hot paths.
+///
+/// This interface is purpose-built for performance-critical hash tables and deliberately
+/// trades runtime flexibility (e.g. pluggable comparers) for compile-time specialization.
+///
+/// Unlike <see cref="IEqualityComparer{T}"/>, implementations of this interface are expected
+/// to be deterministic, allocation-free, and suitable for use inside tight loops.
+/// </summary>
+/// <typeparam name="TKey">
+/// The type of the keys being hashed and compared.
+/// </typeparam>
+public interface IHasher<TKey>
 {
-    public interface IHasher<TKey>
-    {
-        [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        uint ComputeHash(TKey key);            
+    /// <summary>
+    /// Computes a 32-bit hash code for the specified key.
+    ///
+    /// The returned hash must be consistent with <see cref="Equals"/>:
+    ///
+    /// <list type="bullet">
+    /// <item>If <c>Equals(x, y)</c> returns <see langword="true"/>, then
+    /// <c>ComputeHash(x)</c> and <c>ComputeHash(y)</c> <b>must</b> return the same value.</item>
+    /// <item>Unequal keys may produce identical hashes, but high-quality implementations
+    /// should minimize collisions through good bit diffusion.</item>
+    /// </list>
+    ///
+    /// This method is invoked on every lookup, insertion, and removal operation and is
+    /// therefore on the critical hot path. Implementations must be allocation-free and
+    /// suitable for aggressive inlining.
+    /// </summary>
+    /// <param name="key">The key to hash. Must not be <see langword="null"/>.</param>
+    /// <returns>
+    /// A 32-bit unsigned hash value suitable for bucket indexing and signature derivation.
+    /// </returns>
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    uint ComputeHash(TKey key);
 
-    }
+    /// <summary>
+    /// Determines whether two keys are considered equal.
+    ///
+    /// Implementations must obey the standard equality contract
+    /// (reflexive, symmetric, and transitive).
+    ///
+    /// This method is on the hot path for all map operations and should be implemented
+    /// using the cheapest comparison possible:
+    ///
+    /// <list type="bullet">
+    /// <item>For value types, this typically maps to <c>==</c>.</item>
+    /// <item>For reference types, implementations should avoid culture-aware,
+    /// allocation-heavy, or polymorphic comparisons unless explicitly required.</item>
+    /// </list>
+    /// </summary>
+    /// <param name="x">The first key to compare.</param>
+    /// <param name="y">The second key to compare.</param>
+    /// <returns>
+    /// <see langword="true"/> if the keys are equal; otherwise, <see langword="false"/>.
+    /// </returns>
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    bool Equals(TKey x, TKey y);
 }

src/DenseMap.cs

@@ -88,7 +88,7 @@ public DenseMap() : base(16, 0.875) { }
 /// <typeparam name="THasher">
 /// A struct implementing <see cref="Hasher.IHasher{TKey}"/> to provide an optimized hashing function.
 /// Using a struct-based hasher avoids virtual method calls and allows aggressive inlining.</typeparam>
-public class DenseMap<TKey, TValue, THasher> where THasher : struct, Hasher.IHasher<TKey>
+public class DenseMap<TKey, TValue, THasher> where THasher : struct, IHasher<TKey>
 {
     #region Properties
 
@@ -210,7 +210,6 @@ public IEnumerable<TValue> Values
     private uint _lengthMinusOne;
     private readonly double _loadFactor;
     private readonly THasher _hasher;
-    private readonly IEqualityComparer<TKey> _comparer;
 
     #endregion
 
@@ -275,8 +274,7 @@ public DenseMap(uint length, double loadFactor)
         }
 
         _maxLookupsBeforeResize = (uint)(_length * _loadFactor);
-        _comparer = EqualityComparer<TKey>.Default;
-
+  
         _controlBytes = GC.AllocateArray<sbyte>((int)_length + 16);
         _entries = GC.AllocateArray<Entry>((int)_length + 16);
 
@@ -349,7 +347,7 @@ public void Emplace(TKey key, TValue value)
                 // Find the lowest set bit in `mask` (first matching position). 
                 ref var entry = ref Find(_entries, index + (uint)BitOperations.TrailingZeroCount(resultMask));
                 // If a matching key is found, update the entry's value and return the old value.
-                if (_comparer.Equals(entry.Key, key))
+                if (_hasher.Equals(entry.Key, key))
                 {
                     entry.Value = value;
                     return;
@@ -445,7 +443,7 @@ public bool Get(TKey key, out TValue value)
                 // Retrieve the entry corresponding to the matched bit position within the map's entries.
                 var entry = Find(_entries, index + (uint)bitPos);
                 // Check if the entry's key matches the specified key using the equality comparer.
-                if (_comparer.Equals(entry.Key, key))
+                if (_hasher.Equals(entry.Key, key))
                 {
                     // If a match is found, set the output value and return true.
                     value = entry.Value;
@@ -529,7 +527,7 @@ public ref TValue GetValueRefOrAddDefault(TKey key)
                 // Use `bitPos` to access the corresponding entry in `_entries`.
                 ref var entry = ref Find(_entries, index + (uint)bitPos);
                 // If a matching key is found, update the entry's value and return the old value.
-                if (_comparer.Equals(entry.Key, key))
+                if (_hasher.Equals(entry.Key, key))
                 {
                     return ref entry.Value;
                 }
@@ -625,7 +623,7 @@ public bool Update(TKey key, TValue value)
                 ref var entry = ref Find(_entries, index + (uint)bitPos);
 
                 // Check if the current entry's key matches the specified key using the equality comparer.
-                if (_comparer.Equals(entry.Key, key))
+                if (_hasher.Equals(entry.Key, key))
                 {
                     // If a match is found, update the entry's value and return `true` to indicate success.
                     entry.Value = value;
@@ -708,8 +706,8 @@ public bool Remove(TKey key)
                 var i = index + (uint)bitPos;
 
                 // Check if the entry at the matched position has a key that equals the specified key.
-                // Use `_comparer` to ensure accurate key comparison.              
-                if (_comparer.Equals(Find(_entries, i).Key, key))
+                // Use `_hasher` to ensure accurate key comparison.              
+                if (_hasher.Equals(Find(_entries, i).Key, key))
                 {
                     // If the group that contains the entry to be removed has an empty slot (an unoccupied slot that is marked empty rather than as a tombstone), this indicates that any probe sequence for a key would terminate upon reaching that empty slot.
                     // Since probe sequences terminate at the first empty slot they encounter, having an empty slot in the group means that removing the current entry without placing a tombstone won’t disrupt probe chains.
@@ -807,8 +805,8 @@ public bool Contains(TKey key)
                 // Get the position of the first set bit in `mask`, indicating a potential key match.
                 var bitPos = BitOperations.TrailingZeroCount(mask);
                 // Check if the entry at this position has a key that matches the specified key.
-                // Use `_comparer` to ensure accurate key comparison.
-                if (_comparer.Equals(Find(_entries, index + (uint)bitPos).Key, key))
+                // Use `_hasher` to ensure accurate key comparison.
+                if (_hasher.Equals(Find(_entries, index + (uint)bitPos).Key, key))
                 {
                     // If a match is found, return `true` to indicate the key exists in the map.
                     return true;

src/Faster.Map.csproj

@@ -3,19 +3,19 @@
     <ImplicitUsings>false</ImplicitUsings>
     <Nullable>disable</Nullable>
     <LangVersion>preview</LangVersion>
-    <TargetFrameworks>net9.0;net8.0;net7.0</TargetFrameworks>
+    <TargetFrameworks>net9.0;net8.0;net7.0;</TargetFrameworks>
     <LangVersion>Latest</LangVersion>
     <Authors>Wiljan Ruizendaal</Authors>
     <PackageReadmeFile>README.md</PackageReadmeFile>
     <CopyRight>MIT</CopyRight>
     <PackageReleaseNotes>
-      minor changes and fixes
+      Add Equals method to IHasher to eliminate virtual key comparisons
     </PackageReleaseNotes>
     <PackageProjectUrl>https://github.com/Wsm2110/Faster.Map</PackageProjectUrl>
-    <AssemblyVersion>7.0.2</AssemblyVersion>
-    <FileVersion>7.0.2</FileVersion>
+    <AssemblyVersion>7.1.0</AssemblyVersion>
+    <FileVersion>7.1.0</FileVersion>
     <Title>Fastest .net hashmap</Title>
-    <Version>7.0.1</Version>
+    <Version>7.1.0</Version>
     <GeneratePackageOnBuild>True</GeneratePackageOnBuild>
     <Description>
       Incredibly fast hashmap