Make lock contention tracking opt-in for better write throughput

Contention metrics (AtomicInteger increments, tryLock probing) added
measurable overhead on every put/remove. Now disabled by default;
enable via builder().trackContentionMetrics(true) when diagnostics
are needed. When off, each write does a single lock() instead of
tryLock()+lock() plus 2+ atomic counter increments.

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

Author: jdereg

changelog.md

@@ -49,6 +49,10 @@
 * **PERFORMANCE**: `MultiKeyMap` - `keySet()` and `values()` no longer rebuild full `entrySet()`
   * `values()` now iterates buckets directly, skipping all key reconstruction (`reconstructKey()`) and `SimpleEntry` allocation
   * `keySet()` now iterates buckets directly, skipping `SimpleEntry` wrapper allocation
+* **PERFORMANCE**: `MultiKeyMap` - Lock contention tracking is now opt-in via `trackContentionMetrics(true)`
+  * Eliminates 2+ `AtomicInteger` CAS operations per `put`/`remove` call when tracking is disabled (default)
+  * Also skips the `tryLock()`-then-`lock()` contention detection pattern, using a single `lock()` call instead
+  * Enable via `MultiKeyMap.builder().trackContentionMetrics(true)` when diagnostics are needed
 
 #### 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

@@ -422,6 +422,7 @@ public enum CollectionKeyMode {
     private final boolean simpleKeysMode;
     private final boolean valueBasedEquality;
     private final boolean caseSensitive;
+    private final boolean trackContentionMetrics;
     private static final float DEFAULT_LOAD_FACTOR = 0.75f;
 
     // Cached hashCode for performance (invalidated on mutations)
@@ -518,6 +519,7 @@ private MultiKeyMap(Builder<V> builder) {
         this.simpleKeysMode = builder.simpleKeysMode;
         this.valueBasedEquality = builder.valueBasedEquality;
         this.caseSensitive = builder.caseSensitive;
+        this.trackContentionMetrics = builder.trackContentionMetrics;
 
         for (int i = 0; i < STRIPE_COUNT; i++) {
             stripeLocks[i] = new ReentrantLock();
@@ -590,6 +592,7 @@ public static class Builder<V> {
         private boolean simpleKeysMode = false;
         private boolean valueBasedEquality = true;  // Default: cross-type numeric matching
         private boolean caseSensitive = true;  // Default: case-sensitive string comparison
+        private boolean trackContentionMetrics = false;  // Default: off for maximum write throughput
 
         // Private constructor - instantiate via MultiKeyMap.builder()
         private Builder() {}
@@ -710,6 +713,22 @@ public Builder<V> caseSensitive(boolean caseSensitive) {
             return this;
         }
 
+        /**
+         * Enables or disables lock contention metrics tracking.
+         * <p>When enabled, the map tracks per-stripe lock acquisition counts and contention
+         * events using atomic counters. This adds measurable overhead (multiple {@code AtomicInteger}
+         * increments per write operation) but provides diagnostic data accessible via
+         * {@link MultiKeyMap#printContentionStatistics()}.</p>
+         * <p>Default is {@code false} (disabled) for maximum write throughput.</p>
+         *
+         * @param track {@code true} to enable contention tracking, {@code false} to disable
+         * @return this builder instance for method chaining
+         */
+        public Builder<V> trackContentionMetrics(boolean track) {
+            this.trackContentionMetrics = track;
+            return this;
+        }
+
         /**
          * Copies configuration from an existing MultiKeyMap.
          * <p>This copies all configuration settings including capacity, load factor,
@@ -726,6 +745,7 @@ public Builder<V> from(MultiKeyMap<?> source) {
             this.simpleKeysMode = source.simpleKeysMode;
             this.valueBasedEquality = source.valueBasedEquality;
             this.caseSensitive = source.caseSensitive;
+            this.trackContentionMetrics = source.trackContentionMetrics;
             return this;
         }
 
@@ -992,16 +1012,21 @@ private ReentrantLock getStripeLock(int hash) {
     }
 
     private void lockAllStripes() {
-        int contended = 0;
-        for (ReentrantLock lock : stripeLocks) {
-            // Use tryLock() to accurately detect contention
-            if (!lock.tryLock()) {
-                contended++;
-                lock.lock(); // Now wait for the lock
+        if (trackContentionMetrics) {
+            int contended = 0;
+            for (ReentrantLock lock : stripeLocks) {
+                if (!lock.tryLock()) {
+                    contended++;
+                    lock.lock();
+                }
+            }
+            globalLockAcquisitions.incrementAndGet();
+            if (contended > 0) globalLockContentions.incrementAndGet();
+        } else {
+            for (ReentrantLock lock : stripeLocks) {
+                lock.lock();
             }
         }
-        globalLockAcquisitions.incrementAndGet();
-        if (contended > 0) globalLockContentions.incrementAndGet();
     }
 
     private void unlockAllStripes() {
@@ -3114,23 +3139,29 @@ private V putInternal(MultiKey<V> newKey) {
         V old;
         boolean resize;
 
-        // Use tryLock() to accurately detect contention
-        boolean contended = !lock.tryLock();
-        if (contended) {
-            // Failed to acquire immediately - this is true contention
-            lock.lock(); // Now wait for the lock
-            contentionCount.incrementAndGet();
-            stripeLockContention[stripe].incrementAndGet();
-        }
-
-        try {
-            totalLockAcquisitions.incrementAndGet();
-            stripeLockAcquisitions[stripe].incrementAndGet();
-
-            old = putNoLock(newKey);
-            resize = atomicSize.get() > buckets.length() * loadFactor;
-        } finally {
-            lock.unlock();
+        if (trackContentionMetrics) {
+            boolean contended = !lock.tryLock();
+            if (contended) {
+                lock.lock();
+                contentionCount.incrementAndGet();
+                stripeLockContention[stripe].incrementAndGet();
+            }
+            try {
+                totalLockAcquisitions.incrementAndGet();
+                stripeLockAcquisitions[stripe].incrementAndGet();
+                old = putNoLock(newKey);
+                resize = atomicSize.get() > buckets.length() * loadFactor;
+            } finally {
+                lock.unlock();
+            }
+        } else {
+            lock.lock();
+            try {
+                old = putNoLock(newKey);
+                resize = atomicSize.get() > buckets.length() * loadFactor;
+            } finally {
+                lock.unlock();
+            }
         }
 
         resizeRequest(resize);
@@ -3355,22 +3386,27 @@ private V removeInternal(final MultiKey<V> removeKey) {
         ReentrantLock lock = stripeLocks[stripe];
         V old;
 
-        // Use tryLock() to accurately detect contention
-        boolean contended = !lock.tryLock();
-        if (contended) {
-            // Failed to acquire immediately - this is true contention
-            lock.lock(); // Now wait for the lock
-            contentionCount.incrementAndGet();
-            stripeLockContention[stripe].incrementAndGet();
-        }
-
-        try {
-            totalLockAcquisitions.incrementAndGet();
-            stripeLockAcquisitions[stripe].incrementAndGet();
-
-            old = removeNoLock(removeKey);
-        } finally {
-            lock.unlock();
+        if (trackContentionMetrics) {
+            boolean contended = !lock.tryLock();
+            if (contended) {
+                lock.lock();
+                contentionCount.incrementAndGet();
+                stripeLockContention[stripe].incrementAndGet();
+            }
+            try {
+                totalLockAcquisitions.incrementAndGet();
+                stripeLockAcquisitions[stripe].incrementAndGet();
+                old = removeNoLock(removeKey);
+            } finally {
+                lock.unlock();
+            }
+        } else {
+            lock.lock();
+            try {
+                old = removeNoLock(removeKey);
+            } finally {
+                lock.unlock();
+            }
         }
 
         return old;

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

@@ -26,9 +26,17 @@ private static int spread(int h) {
         return h ^ (h >>> 16);
     }
 
+    /** Creates a small map with contention tracking enabled */
+    private static MultiKeyMap<String> createTrackedMap() {
+        return MultiKeyMap.<String>builder()
+                .capacity(16)
+                .trackContentionMetrics(true)
+                .build();
+    }
+
     @Test
     void testPutTracksAcquisitionOnCorrectStripe() throws Exception {
-        MultiKeyMap<String> map = new MultiKeyMap<>(16);
+        MultiKeyMap<String> map = createTrackedMap();
 
         // Access internals via reflection
         Field stripeAcqField = MultiKeyMap.class.getDeclaredField("stripeLockAcquisitions");
@@ -78,7 +86,7 @@ void testPutTracksAcquisitionOnCorrectStripe() throws Exception {
 
     @Test
     void testRemoveTracksAcquisitionOnCorrectStripe() throws Exception {
-        MultiKeyMap<String> map = new MultiKeyMap<>(16);
+        MultiKeyMap<String> map = createTrackedMap();
 
         Field stripeAcqField = MultiKeyMap.class.getDeclaredField("stripeLockAcquisitions");
         stripeAcqField.setAccessible(true);
@@ -127,7 +135,7 @@ void testRemoveTracksAcquisitionOnCorrectStripe() throws Exception {
 
     @Test
     void testNoAcquisitionsAboveTableSizeStripes() throws Exception {
-        MultiKeyMap<String> map = new MultiKeyMap<>(16);
+        MultiKeyMap<String> map = createTrackedMap();
 
         Field stripeAcqField = MultiKeyMap.class.getDeclaredField("stripeLockAcquisitions");
         stripeAcqField.setAccessible(true);