Add hash spreading to MultiKeyMap for better bucket distribution

Apply ConcurrentHashMap-style spread (h ^ (h >>> 16)) at all 7 bucket
selection points to mix higher hash bits into lower bits, reducing
collisions when the table is small. Stored hashes are unchanged.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: jdereg

changelog.md

@@ -42,6 +42,10 @@
   * `getMultiKey()` and `containsMultiKey()` methods never nulled out array entries after use
   * In thread-pool environments, this pinned references to user objects for the lifetime of the thread
   * Added `try/finally` cleanup in all 8 methods
+* **PERFORMANCE**: `MultiKeyMap` - Hash spreading for better bucket distribution
+  * Added `spread(h) = h ^ (h >>> 16)` at all bucket selection points (same technique as `ConcurrentHashMap`)
+  * When the table is small, only low-order bits select the bucket; spreading mixes in higher bits to reduce collisions
+  * Applied at all 7 bucket index computation sites; stored hashes are unchanged
 
 #### 4.90.0 2026-02-02
 * **BUG FIX**: `DeepEquals` - URL comparison now uses string representation instead of `URL.equals()`

src/main/java/com/cedarsoftware/util/MultiKeyMap.java

@@ -969,12 +969,22 @@ private static int hashDouble(double d) {
         return (int) (bits ^ (bits >>> 32));
     }
 
+    /**
+     * Spreads higher bits of the hash into lower bits to improve bucket distribution.
+     * When the table is small, only the low-order bits select the bucket. Without
+     * spreading, hashes that differ only in higher bits collide in the same bucket.
+     * This is the same technique used by {@code ConcurrentHashMap}.
+     */
+    private static int spread(int h) {
+        return h ^ (h >>> 16);
+    }
+
     private int getStripeIndex(int hash) {
         // Use bucket index for stripe selection to reduce false contention
         // between independent buckets that happen to have same low-order hash bits
         final AtomicReferenceArray<MultiKey<V>[]> table = buckets;  // Volatile read of buckets
         final int mask = table.length() - 1;  // Array length is immutable
-        return (hash & mask) & STRIPE_MASK;
+        return (spread(hash) & mask) & STRIPE_MASK;
     }
 
     private ReentrantLock getStripeLock(int hash) {
@@ -1165,7 +1175,7 @@ private MultiKey<V> findSimpleOrComplexKey(Object key) {
                 int hash = computeElementHash(key, caseSensitive);
                 final AtomicReferenceArray<MultiKey<V>[]> table = buckets;
                 final int mask = table.length() - 1;
-                final int index = hash & mask;
+                final int index = spread(hash) & mask;
                 final MultiKey<V>[] chain = table.get(index);
                 if (chain != null) {
                     // Fast scan for single-key entries only
@@ -2072,7 +2082,7 @@ private static int expandAndHash(Object current, List<Object> result, IdentitySe
     private MultiKey<V> findEntryWithPrecomputedHash(final Object normalizedKey, final int hash) {
         final AtomicReferenceArray<MultiKey<V>[]> table = buckets;  // Volatile read of buckets
         final int mask = table.length() - 1;  // Array length is immutable
-        final int index = hash & mask;
+        final int index = spread(hash) & mask;
 
         final MultiKey<V>[] chain = table.get(index);
         if (chain == null) {
@@ -3132,7 +3142,7 @@ private V getNoLock(MultiKey<V> lookupKey) {
         int hash = lookupKey.hash;
         final AtomicReferenceArray<MultiKey<V>[]> table = buckets;  // Volatile read of buckets
         final int mask = table.length() - 1;  // Array length is immutable
-        int index = hash & mask;
+        int index = spread(hash) & mask;
         MultiKey<V>[] chain = table.get(index);
 
         if (chain == null) return null;
@@ -3150,7 +3160,7 @@ private V putNoLock(MultiKey<V> newKey) {
         int hash = newKey.hash;
         final AtomicReferenceArray<MultiKey<V>[]> table = buckets;  // Volatile read of buckets
         final int mask = table.length() - 1;  // Array length is immutable
-        int index = hash & mask;
+        int index = spread(hash) & mask;
         MultiKey<V>[] chain = table.get(index);
 
         if (chain == null) {
@@ -3371,7 +3381,7 @@ private V removeNoLock(MultiKey<V> removeKey) {
         int hash = removeKey.hash;
         final AtomicReferenceArray<MultiKey<V>[]> table = buckets;  // Volatile read of buckets
         final int mask = table.length() - 1;  // Array length is immutable
-        int index = hash & mask;
+        int index = spread(hash) & mask;
         MultiKey<V>[] chain = table.get(index);
 
         if (chain == null) return null;
@@ -3426,7 +3436,7 @@ private void resizeInternal() {
 
     @SuppressWarnings("unchecked")
     private int rehashEntry(MultiKey<V> entry, AtomicReferenceArray<MultiKey<V>[]> target) {
-        int index = entry.hash & (target.length() - 1);
+        int index = spread(entry.hash) & (target.length() - 1);
         MultiKey<V>[] chain = target.get(index);
         if (chain == null) {
             target.set(index, new MultiKey[]{entry});

src/test/java/com/cedarsoftware/util/MultiKeyMapStripeTrackingTest.java

@@ -13,18 +13,19 @@
 /**
  * Test for bug #5: Stripe contention diagnostics track the wrong stripe.
  *
- * Bug: putInternal and removeInternal compute the stripe index for contention
+ * Bug: putInternal and removeInternal computed the stripe index for contention
  * tracking as {@code hash & STRIPE_MASK}, but getStripeLock computes it as
- * {@code (hash & tableMask) & STRIPE_MASK}. When the table is smaller than
- * STRIPE_COUNT (e.g., default capacity 16 vs STRIPE_COUNT 32), these produce
- * different values. For example, with hash=112, tableMask=15, STRIPE_MASK=31:
- *   - getStripeLock:  (112 & 15) & 31 = 0  (actual lock acquired on stripe 0)
- *   - putInternal:     112 & 31      = 16  (contention tracked on stripe 16)
- *
- * This means per-stripe contention metrics are attributed to the wrong stripes.
+ * {@code (spread(hash) & tableMask) & STRIPE_MASK}. When the table is smaller
+ * than STRIPE_COUNT, these produce different values, so per-stripe metrics
+ * were attributed to incorrect stripes.
  */
 class MultiKeyMapStripeTrackingTest {
 
+    /** Mirrors MultiKeyMap.spread() */
+    private static int spread(int h) {
+        return h ^ (h >>> 16);
+    }
+
     @Test
     void testPutTracksAcquisitionOnCorrectStripe() throws Exception {
         MultiKeyMap<String> map = new MultiKeyMap<>(16);
@@ -48,36 +49,31 @@ void testPutTracksAcquisitionOnCorrectStripe() throws Exception {
             return; // Can't trigger on this machine/config
         }
 
-        // Find a key whose hash has bits set in (stripeMask & ~tableMask),
-        // causing the buggy and correct stripe computations to differ.
-        int diffBits = stripeMask & ~tableMask;
-
+        // Find a key where the correct stripe (with spread) differs from
+        // the old buggy stripe (hash & STRIPE_MASK without spread or tableMask)
         String testKey = null;
         int testHash = 0;
         for (int i = 0; i < 10000; i++) {
             String candidate = "key" + i;
             int h = candidate.hashCode();
-            if ((h & diffBits) != 0) {
+            int correctStripe = (spread(h) & tableMask) & stripeMask;
+            int buggyStripe = h & stripeMask;
+            if (correctStripe != buggyStripe) {
                 testKey = candidate;
                 testHash = h;
                 break;
             }
         }
-        assertNotNull(testKey, "Should find a key with hash bits in the differing range");
+        assertNotNull(testKey, "Should find a key where correct and buggy stripes differ");
 
-        int correctStripe = (testHash & tableMask) & stripeMask;
-        int buggyStripe = testHash & stripeMask;
-        assertNotEquals(correctStripe, buggyStripe,
-                "Precondition: correct and buggy stripes must differ for this key");
+        int expectedStripe = (spread(testHash) & tableMask) & stripeMask;
 
         // Perform a put
         map.put(testKey, "value");
 
-        // Verify acquisition was tracked on the correct stripe (the one matching getStripeLock)
-        assertEquals(1, acq[correctStripe].get(),
-                "Acquisition should be tracked on stripe " + correctStripe + " (matching getStripeLock)");
-        assertEquals(0, acq[buggyStripe].get(),
-                "Stripe " + buggyStripe + " should have no acquisitions (wrong stripe)");
+        // Verify acquisition was tracked on the correct stripe
+        assertEquals(1, acq[expectedStripe].get(),
+                "Acquisition should be tracked on stripe " + expectedStripe + " (matching getStripeIndex)");
     }
 
     @Test
@@ -101,36 +97,32 @@ void testRemoveTracksAcquisitionOnCorrectStripe() throws Exception {
             return;
         }
 
-        int diffBits = stripeMask & ~tableMask;
-
         String testKey = null;
         int testHash = 0;
         for (int i = 0; i < 10000; i++) {
             String candidate = "key" + i;
             int h = candidate.hashCode();
-            if ((h & diffBits) != 0) {
+            int correctStripe = (spread(h) & tableMask) & stripeMask;
+            int buggyStripe = h & stripeMask;
+            if (correctStripe != buggyStripe) {
                 testKey = candidate;
                 testHash = h;
                 break;
             }
         }
         assertNotNull(testKey);
 
-        int correctStripe = (testHash & tableMask) & stripeMask;
-        int buggyStripe = testHash & stripeMask;
-        assertNotEquals(correctStripe, buggyStripe);
+        int expectedStripe = (spread(testHash) & tableMask) & stripeMask;
 
         // Put the key first (this also increments the correct stripe's counter)
         map.put(testKey, "value");
-        int acqAfterPut = acq[correctStripe].get();
+        int acqAfterPut = acq[expectedStripe].get();
 
         // Now remove it - should also track on the correct stripe
         map.remove(testKey);
 
-        assertEquals(acqAfterPut + 1, acq[correctStripe].get(),
-                "Remove acquisition should be tracked on stripe " + correctStripe);
-        assertEquals(0, acq[buggyStripe].get(),
-                "Stripe " + buggyStripe + " should have no acquisitions");
+        assertEquals(acqAfterPut + 1, acq[expectedStripe].get(),
+                "Remove acquisition should be tracked on stripe " + expectedStripe);
     }
 
     @Test
@@ -155,8 +147,8 @@ void testNoAcquisitionsAboveTableSizeStripes() throws Exception {
             map.put("item" + i, "val" + i);
         }
 
-        // With table size 16 and stripe count 32, the correct stripe index
-        // is (hash & 15) & 31 which can only produce values in [0, 15].
+        // With table size 16 and stripe count 32, the stripe index is
+        // (spread(hash) & 15) & 31 which can only produce values in [0, 15].
         // Stripes [16, 31] should never receive acquisitions.
         for (int s = tableSize; s < acq.length; s++) {
             assertEquals(0, acq[s].get(),