Add custom hash mix functions for SyncMap (#17)

vectrixdevelops · web-flow · commit 1b8bb215a8bb · 2025-10-25T17:48:53.000+13:00
* improve(syncmap): add the ability to set a custom hash mix function

* fix(syncmap): correct constructor default value for load factor
diff --git a/collections/src/jmh/java/space/vectrix/sync/collections/SyncMapBenchmark.java b/collections/src/jmh/java/space/vectrix/sync/collections/SyncMapBenchmark.java
@@ -72,7 +72,7 @@ public void setup() {
       final boolean prepopulate = "prepopulate".equalsIgnoreCase(this.mode);
 
       switch(this.implementation) {
-        case "SyncMap" -> this.map = presized ? new SyncMap<>(this.size) : new SyncMap<>();
+        case "SyncMap" -> this.map = presized ? new SyncMap<>(Hashing.FASTEST_MIX, this.size) : new SyncMap<>(Hashing.FASTEST_MIX);
         case "ConcurrentHashMap" -> this.map = presized ? new ConcurrentHashMap<>(this.size) : new ConcurrentHashMap<>();
         case "SynchronizedMap" -> this.map = presized
           ? Collections.synchronizedMap(new HashMap<>(this.size))
diff --git a/collections/src/main/java/space/vectrix/sync/collections/Hashing.java b/collections/src/main/java/space/vectrix/sync/collections/Hashing.java
@@ -0,0 +1,98 @@
+/*
+ * This file is part of sync, licensed under the MIT License.
+ *
+ * Copyright (c) 2025 vectrix.space
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+package space.vectrix.sync.collections;
+
+import java.util.concurrent.ThreadLocalRandom;
+import org.jetbrains.annotations.ApiStatus;
+
+/**
+ * Provides common constants and utilities for hashing operations used across
+ * the collections framework.
+ *
+ * @author Vectrix
+ * @since 1.0.0
+ */
+@ApiStatus.Internal
+public interface Hashing {
+  /**
+   * The bitmask applied to ensure hash values are non-negative and fit within
+   * the usable range of 32-bit signed integers.
+   */
+  /* package */ int HASH_BITS = 0x7FFFFFFF;
+
+  /**
+   * A random seed used to introduce variability into hash computations,
+   * reducing predictability and the likelihood of collision attacks.
+   */
+  /* package */ int HASH_SEED = ThreadLocalRandom.current().nextInt();
+
+  /**
+   * A hash mixing function optimized for raw speed with minimal transformation.
+   * Provides adequate distribution for small or moderate-sized maps but may
+   * degrade performance with large datasets or many similar keys.
+   */
+  MixFunction FASTEST_MIX = x -> (x ^ (x >>> 16)) & Hashing.HASH_BITS;
+
+  /**
+   * A hash mixing function that balances performance and moderate hash
+   * distribution. Suitable for medium-sized maps, but may still degrade under
+   * high key similarity or very large data sets.
+   */
+  MixFunction FAST_MIX = x -> {
+    x ^= (x >>> 16);
+    x ^= (x >>> 13);
+    return x & Hashing.HASH_BITS;
+  };
+
+  /**
+   * A hash mixing function that emphasizes stronger distribution while
+   * maintaining good performance. Incorporates {@link #HASH_SEED} to randomize
+   * results and reduce vulnerability to hash collision attacks.
+   */
+  MixFunction BALANCED_MIX = x -> {
+    x ^= Hashing.HASH_SEED;
+    x ^= (x >>> 16);
+    x ^= (x >>> 13);
+    return x & Hashing.HASH_BITS;
+  };
+
+  /**
+   * Represents a hash mixing function to distribute key-value pairs into
+   * buckets using an {@code int} hash.
+   *
+   * @author Vectrix
+   * @since 1.0.0
+   */
+  @FunctionalInterface
+  interface MixFunction {
+    /**
+     * Mixes the provided hash for distributing key-value pairs into buckets.
+     *
+     * @param hash the hash
+     * @return the mixed hash
+     * @since 1.0.0
+     */
+    int mix(final int hash);
+  }
+}
diff --git a/collections/src/main/java/space/vectrix/sync/collections/SyncMap.java b/collections/src/main/java/space/vectrix/sync/collections/SyncMap.java
@@ -100,11 +100,6 @@ public class SyncMap<K, V> extends AbstractMap<K, V> implements ConcurrentMap<K,
    */
   /* package */ static final int MINIMUM_TRANSFER_STRIDE = 16;
 
-  /**
-   * Represents the number of usable bits for node hash keys.
-   */
-  /* package */ static final int HASH_BITS = 0x7FFFFFFF;
-
   /**
    * Represents the hash for a node that has been transferred.
    */
@@ -122,17 +117,6 @@ public class SyncMap<K, V> extends AbstractMap<K, V> implements ConcurrentMap<K,
 
   /* ------------------------------ < Utilities > ------------------------------ */
 
-  /**
-   * Spreads the given hash value to a positive value and forces the top bit to
-   * 0.
-   *
-   * @param value the value to spread
-   * @return the spread value
-   */
-  /* package */ static int spread(final int value) {
-    return (value ^ (value >>> 16)) & SyncMap.HASH_BITS;
-  }
-
   /**
    * Returns the optimal table size depending on the given capacity.
    *
@@ -225,6 +209,11 @@ public class SyncMap<K, V> extends AbstractMap<K, V> implements ConcurrentMap<K,
 
   /* ------------------------------ < Fields > ------------------------------ */
 
+  /**
+   * Represents the mix function for distributing hashes in the map.
+   */
+  /* package */ final transient Hashing.MixFunction mixFunction;
+
   /**
    * Represents the load factor for resizing the map.
    */
@@ -297,40 +286,77 @@ public class SyncMap<K, V> extends AbstractMap<K, V> implements ConcurrentMap<K,
   /* ------------------------- < Public Operations > ------------------------- */
 
   /**
-   * Initializes a new {@link SyncMap} with {@link SyncMap#DEFAULT_CAPACITY} and
-   * {@link SyncMap#DEFAULT_LOAD_FACTOR}.
+   * Initializes a new {@link SyncMap} with {@link Hashing#FAST_MIX},
+   * {@link SyncMap#DEFAULT_CAPACITY} and {@link SyncMap#DEFAULT_LOAD_FACTOR}.
    *
    * @since 1.0.0
    */
   public SyncMap() {
-    this(SyncMap.DEFAULT_CAPACITY);
+    this(Hashing.FAST_MIX);
   }
 
   /**
-   * Initializes a new {@link SyncMap} with the given initial capacity and
-   * {@link SyncMap#DEFAULT_LOAD_FACTOR}.
+   * Initializes a new {@link SyncMap} with the given mix function,
+   * {@link SyncMap#DEFAULT_CAPACITY} and {@link SyncMap#DEFAULT_LOAD_FACTOR}.
+   *
+   * @param mixFunction the mix function
+   * @since 1.0.0
+   */
+  public SyncMap(final Hashing.MixFunction mixFunction) {
+    this(mixFunction, SyncMap.DEFAULT_CAPACITY);
+  }
+
+  /**
+   * Initializes a new {@link SyncMap} with {@link Hashing#FAST_MIX}, the
+   * given initial capacity and {@link SyncMap#DEFAULT_LOAD_FACTOR}.
    *
    * @param initialCapacity the initial capacity
    * @since 1.0.0
    */
   public SyncMap(final int initialCapacity) {
-    this(initialCapacity, SyncMap.DEFAULT_LOAD_FACTOR);
+    this(Hashing.FAST_MIX, initialCapacity);
   }
 
   /**
-   * Initializes a new {@link SyncMap} with the given initial capacity and load
-   * factor.
+   * Initializes a new {@link SyncMap} with the given mix function, the given
+   * initial capacity and {@link SyncMap#DEFAULT_LOAD_FACTOR}.
+   *
+   * @param mixFunction the mix function
+   * @param initialCapacity the initial capacity
+   * @since 1.0.0
+   */
+  public SyncMap(final Hashing.MixFunction mixFunction, final int initialCapacity) {
+    this(mixFunction, initialCapacity, SyncMap.DEFAULT_LOAD_FACTOR);
+  }
+
+  /**
+   * Initializes a new {@link SyncMap} with {@link Hashing#FAST_MIX}, the
+   * given initial capacity and the given load factor.
    *
    * @param initialCapacity the initial capacity
    * @param loadFactor the load factor
    * @since 1.0.0
    */
-  @SuppressWarnings({"rawtypes", "unchecked"})
   public SyncMap(final int initialCapacity, final float loadFactor) {
+    this(Hashing.FAST_MIX, initialCapacity, loadFactor);
+  }
+
+  /**
+   * Initializes a new {@link SyncMap} with the given mix function, the given
+   * initial capacity and the given load factor.
+   *
+   * @param mixFunction the mix function
+   * @param initialCapacity the initial capacity
+   * @param loadFactor the load factor
+   * @since 1.0.0
+   */
+  @SuppressWarnings({"rawtypes", "unchecked"})
+  public SyncMap(final Hashing.MixFunction mixFunction, final int initialCapacity, final float loadFactor) {
     final int capacity = initialCapacity >= SyncMap.MAXIMUM_CAPACITY
       ? SyncMap.MAXIMUM_CAPACITY
       : SyncMap.tableSizeFor(initialCapacity);
 
+    this.mixFunction = mixFunction;
     this.loadFactor = loadFactor;
     this.capacity = capacity;
 
@@ -358,7 +384,7 @@ public boolean containsKey(final Object key) {
     Node<K, V> node, nextNode;
     int nodeHash; K nodeKey;
 
-    final int hash = SyncMap.spread(key.hashCode());
+    final int hash = this.mixFunction.mix(key.hashCode());
 
     if(length > 0 && (node = SyncMap.getNode(table, (length - 1) & hash)) != null) {
       if((nodeHash = node.hash) == hash) {
@@ -416,7 +442,7 @@ public boolean containsKey(final Object key) {
     Node<K, V> node, nextNode;
     int nodeHash; K nodeKey;
 
-    final int hash = SyncMap.spread(key.hashCode());
+    final int hash = this.mixFunction.mix(key.hashCode());
 
     if(length > 0 && (node = SyncMap.getNode(table, (length - 1) & hash)) != null) {
       if((nodeHash = node.hash) == hash) {
@@ -475,7 +501,7 @@ public V getOrDefault(final Object key, final V defaultValue) {
     Node<K, V> node, nextNode;
     int nodeHash; K nodeKey;
 
-    final int hash = SyncMap.spread(key.hashCode());
+    final int hash = this.mixFunction.mix(key.hashCode());
 
     if(length > 0 && (node = SyncMap.getNode(table, (length - 1) & hash)) != null) {
       if((nodeHash = node.hash) == hash) {
@@ -534,7 +560,7 @@ public V getOrDefault(final Object key, final V defaultValue) {
     Node<K, V>[] immutable, mutable = null; int length;
     Node<K, V> node; K nodeKey;
 
-    final int hash = SyncMap.spread(key.hashCode());
+    final int hash = this.mixFunction.mix(key.hashCode());
 
     V next;
     retry: for(; ; ) {
@@ -642,7 +668,7 @@ public V getOrDefault(final Object key, final V defaultValue) {
     Node<K, V>[] immutable, mutable; int length;
     Node<K, V> node; K nodeKey;
 
-    final int hash = SyncMap.spread(key.hashCode());
+    final int hash = this.mixFunction.mix(key.hashCode());
 
     V next; long count = 0L;
     retry: for(; ; ) {
@@ -738,7 +764,7 @@ public V getOrDefault(final Object key, final V defaultValue) {
     Node<K, V>[] immutable, mutable = null; int length;
     Node<K, V> node; K nodeKey;
 
-    final int hash = SyncMap.spread(key.hashCode());
+    final int hash = this.mixFunction.mix(key.hashCode());
 
     V next; long count = 0L;
     retry: for(; ; ) {
@@ -866,7 +892,7 @@ public V getOrDefault(final Object key, final V defaultValue) {
     Node<K, V>[] immutable, mutable = null; int length;
     Node<K, V> node; K nodeKey;
 
-    final int hash = SyncMap.spread(key.hashCode());
+    final int hash = this.mixFunction.mix(key.hashCode());
 
     retry: for(; ; ) {
       immutable = this.immutableTable; length = immutable.length;
@@ -961,7 +987,7 @@ public V getOrDefault(final Object key, final V defaultValue) {
     Node<K, V>[] immutable, mutable = null; int length;
     Node<K, V> node; K nodeKey;
 
-    final int hash = SyncMap.spread(key.hashCode());
+    final int hash = this.mixFunction.mix(key.hashCode());
 
     retry: for(; ; ) {
       immutable = this.immutableTable; length = immutable.length;
@@ -1094,7 +1120,7 @@ public V getOrDefault(final Object key, final V defaultValue) {
     Node<K, V>[] immutable, mutable; int length;
     Node<K, V> node; K nodeKey;
 
-    final int hash = SyncMap.spread(key.hashCode());
+    final int hash = this.mixFunction.mix(key.hashCode());
 
     Object previous;
     retry: for(; ; ) {
@@ -1179,7 +1205,7 @@ public boolean remove(final Object key, final Object value) {
     Node<K, V>[] immutable, mutable; int length;
     Node<K, V> node; K nodeKey;
 
-    final int hash = SyncMap.spread(key.hashCode());
+    final int hash = this.mixFunction.mix(key.hashCode());
 
     retry: for(; ; ) {
       immutable = this.immutableTable; length = immutable.length;
@@ -1266,7 +1292,7 @@ public boolean remove(final Object key, final Object value) {
     Node<K, V>[] immutable, mutable; int length;
     Node<K, V> node; K nodeKey;
 
-    final int hash = SyncMap.spread(key.hashCode());
+    final int hash = this.mixFunction.mix(key.hashCode());
 
     Object previous;
     retry: for(; ; ) {
@@ -1343,7 +1369,7 @@ public boolean replace(final @NonNull K key, final @NonNull V oldValue, final @N
     Node<K, V>[] immutable, mutable; int length;
     Node<K, V> node; K nodeKey;
 
-    final int hash = SyncMap.spread(key.hashCode());
+    final int hash = this.mixFunction.mix(key.hashCode());
 
     Object previous;
     retry: for(; ; ) {
@@ -1472,11 +1498,14 @@ public void clear() {
   /**
    * {@inheritDoc}
    *
-   * <p>Creating an {@link Iterator} from this view, takes an immutable
-   * snapshot of the entries, meaning, modifications after calling
-   * {@link Set#iterator()} will not be visible. Calling
-   * {@link Iterator#remove()} will work provided the key-value pair is
-   * identical to the pair currently in the map.</p>
+   * <p>The {@link Iterator} produced by this view is weakly consistent: it
+   * iterates over an immutable snapshot captured at iterator creation time.
+   * New insertions after calling {@link Set#iterator()} are not reflected in
+   * the traversal.</p>
+   *
+   * <p>{@link Iterator#remove()} attempts to remove the last returned entry
+   * from the backing map, and succeeds only if the key still maps to the same
+   * value at the time of removal.</p>
    */
   @Override
   public Set<Map.Entry<K, V>> entrySet() {
