Mp 11740 introduce sorted map to fast utils wrapper (#21)

* MP-11740 Introduce Long2ShortMap

* MP-11740 Introduce Long2ShortTreeMap

* MP-11740 Fix intendations

* MP-11740 Restrict TreeMap to 1 bucket

* MP-11740 Update comment

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* MP-11740 Update comment in test

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* MP-11740 Remove unused constant

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* MP-11740 Fix indentation

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Fix formatting in LongShortTreeMap.java to match other map interfaces

Agent-Logs-Url: https://github.com/trivago/fastutil-concurrent-wrapper/sessions/06e81fc3-7af9-46a9-9a6e-9afec03ed2d1

Co-authored-by: sarveswaran-m <34768285+sarveswaran-m@users.noreply.github.com>

* MP-11740 Prevent instantiating TreeMap with more than 1 bucket

* MP-11740 Update version

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>

Author: 3 people

build.gradle

@@ -23,7 +23,7 @@ allprojects {
 }
 
 group 'com.trivago'
-version '0.2.4-SNAPSHOT'
+version '0.3.0-SNAPSHOT'
 
 mavenPublishing {
     coordinates("com.trivago", "fastutil-concurrent-wrapper", "0.2.3")

src/main/java/com/trivago/fastutilconcurrentwrapper/ConcurrentLongShortMapBuilder.java

@@ -0,0 +1,75 @@
+package com.trivago.fastutilconcurrentwrapper;
+
+import com.trivago.fastutilconcurrentwrapper.map.ConcurrentBusyWaitingLongShortMap;
+import com.trivago.fastutilconcurrentwrapper.map.ConcurrentLongShortMap;
+
+public final class ConcurrentLongShortMapBuilder {
+    private MapMode mapMode = MapMode.BLOCKING;
+    private int buckets = 8;
+    private int initialCapacity = 100_000;
+    private float loadFactor = 0.8f;
+    private short defaultValue = LongShortMap.DEFAULT_VALUE;
+
+    private ConcurrentLongShortMapBuilder() {
+
+    }
+
+    public static ConcurrentLongShortMapBuilder newBuilder() {
+        return new ConcurrentLongShortMapBuilder();
+    }
+
+    public ConcurrentLongShortMapBuilder withBuckets(int buckets) {
+        this.buckets = buckets;
+        return this;
+    }
+
+    public ConcurrentLongShortMapBuilder withInitialCapacity(int initialCapacity) {
+        this.initialCapacity = initialCapacity;
+        return this;
+    }
+
+    public ConcurrentLongShortMapBuilder withLoadFactor(float loadFactor) {
+        this.loadFactor = loadFactor;
+        return this;
+    }
+
+    public ConcurrentLongShortMapBuilder withMode(MapMode mapMode) {
+        this.mapMode = mapMode;
+        return this;
+    }
+
+    public ConcurrentLongShortMapBuilder withDefaultValue(short defaultValue) {
+        this.defaultValue = defaultValue;
+        return this;
+    }
+
+    public LongShortMap build() {
+        return mapMode.createMap(this);
+    }
+
+    public enum MapMode {
+        BUSY_WAITING {
+            @Override
+            LongShortMap createMap(ConcurrentLongShortMapBuilder builder) {
+                return new ConcurrentBusyWaitingLongShortMap(
+                        builder.buckets,
+                        builder.initialCapacity,
+                        builder.loadFactor,
+                        builder.defaultValue);
+            }
+        },
+        BLOCKING {
+            @Override
+            LongShortMap createMap(ConcurrentLongShortMapBuilder builder) {
+                return new ConcurrentLongShortMap(
+                        builder.buckets,
+                        builder.initialCapacity,
+                        builder.loadFactor,
+                        builder.defaultValue);
+            }
+        };
+
+        abstract LongShortMap createMap(ConcurrentLongShortMapBuilder builder);
+    }
+}
+

src/main/java/com/trivago/fastutilconcurrentwrapper/ConcurrentLongShortTreeMapBuilder.java

@@ -0,0 +1,50 @@
+package com.trivago.fastutilconcurrentwrapper;
+
+import com.trivago.fastutilconcurrentwrapper.map.ConcurrentBusyWaitingLongShortTreeMap;
+import com.trivago.fastutilconcurrentwrapper.map.ConcurrentLongShortTreeMap;
+
+public final class ConcurrentLongShortTreeMapBuilder {
+    private MapMode mapMode = MapMode.BLOCKING;
+    private short defaultValue = LongShortMap.DEFAULT_VALUE;
+
+    private ConcurrentLongShortTreeMapBuilder() {
+    }
+
+    public static ConcurrentLongShortTreeMapBuilder newBuilder() {
+        return new ConcurrentLongShortTreeMapBuilder();
+    }
+
+
+    public ConcurrentLongShortTreeMapBuilder withMode(MapMode mapMode) {
+        this.mapMode = mapMode;
+        return this;
+    }
+
+    public ConcurrentLongShortTreeMapBuilder withDefaultValue(short defaultValue) {
+        this.defaultValue = defaultValue;
+        return this;
+    }
+
+    public LongShortTreeMap build() {
+        return mapMode.createMap(this);
+    }
+
+    public enum MapMode {
+        BUSY_WAITING {
+            @Override
+            LongShortTreeMap createMap(ConcurrentLongShortTreeMapBuilder builder) {
+                return new ConcurrentBusyWaitingLongShortTreeMap(
+                        builder.defaultValue);
+            }
+        },
+        BLOCKING {
+            @Override
+            LongShortTreeMap createMap(ConcurrentLongShortTreeMapBuilder builder) {
+                return new ConcurrentLongShortTreeMap(
+                        builder.defaultValue);
+            }
+        };
+
+        abstract LongShortTreeMap createMap(ConcurrentLongShortTreeMapBuilder builder);
+    }
+}

src/main/java/com/trivago/fastutilconcurrentwrapper/LongShortMap.java

@@ -0,0 +1,29 @@
+package com.trivago.fastutilconcurrentwrapper;
+
+import it.unimi.dsi.fastutil.longs.Long2ShortFunction;
+
+import java.util.function.BiFunction;
+
+public interface LongShortMap extends PrimitiveLongKeyMap {
+
+    short DEFAULT_VALUE = 0;
+
+    /**
+     * @param key key to get
+     * @return configured LongShortMap.getDefaultValue(), if the key is not present
+     */
+    short get(long key);
+
+    short put(long key, short value);
+
+    short getDefaultValue();
+
+    short remove(long key);
+
+    boolean remove(long key, short value);
+
+    short computeIfAbsent(long key, Long2ShortFunction mappingFunction);
+
+    short computeIfPresent(long key, BiFunction<Long, Short, Short> mappingFunction);
+}
+

src/main/java/com/trivago/fastutilconcurrentwrapper/LongShortTreeMap.java

@@ -0,0 +1,23 @@
+package com.trivago.fastutilconcurrentwrapper;
+
+import it.unimi.dsi.fastutil.longs.Long2ShortMap;
+
+/**
+ * A sorted {@link LongShortMap} that additionally supports a {@code floorEntry()} operation.
+ */
+public interface LongShortTreeMap extends LongShortMap {
+
+    // floorEntry() requires all keys to reside in a single bucket to return
+    // correct results, so the bucket count is fixed at 1.
+    // ToDo: Identify a bucketing methodology that works for TreeMap
+    public static final int BUCKETS = 1;
+
+    /**
+     * Returns the entry with the greatest key less than or equal to the given key,
+     * or {@code null} if no such key exists.
+     *
+     * @param key the key to search for
+     * @return an entry with the greatest key ≤ {@code key}, or {@code null}
+     */
+    Long2ShortMap.Entry floorEntry(long key);
+}

src/main/java/com/trivago/fastutilconcurrentwrapper/impl/longs/FloorableLongShortAVLTreeMap.java

@@ -0,0 +1,75 @@
+package com.trivago.fastutilconcurrentwrapper.impl.longs;
+
+import it.unimi.dsi.fastutil.longs.Long2ShortAVLTreeMap;
+import it.unimi.dsi.fastutil.longs.Long2ShortMap;
+import it.unimi.dsi.fastutil.longs.Long2ShortSortedMap;
+
+/**
+ * Extends {@link Long2ShortAVLTreeMap} with a {@code floorEntry()} method.
+ *
+ * <p>Fastutil's sorted maps do not provide NavigableMap-style floor/ceiling
+ * operations. This class implements {@code floorEntry()} using the
+ * {@link Long2ShortSortedMap#headMap(long)} workaround:
+ *
+ * <pre>
+ *   headMap(key + 1)   → view of all keys &lt; (key + 1), i.e., keys ≤ key
+ *   lastLongKey()      → largest key in that view = floor(key)
+ * </pre>
+ *
+ * <p>The {@code headMap()} call returns a <em>view</em>, not a copy, so memory
+ * overhead is O(1). The additional method-call frame adds negligible latency
+ * (~1 ns) compared to the O(log n) tree traversal (~100–500 ns at 10M entries).
+ *
+ * <p>This wrapper lives in this project's implementation package and provides
+ * floor-entry behavior without relying on fastutil package-private internals.
+ *
+ * @see Long2ShortAVLTreeMap
+ * @see Long2ShortSortedMap#headMap(long)
+ */
+public class FloorableLongShortAVLTreeMap extends Long2ShortAVLTreeMap {
+
+    private static final long serialVersionUID = 1L;
+
+    /**
+     * Returns the entry with the greatest key less than or equal to the given key,
+     * or {@code null} if no such key exists.
+     *
+     * <p>Implementation uses {@code headMap(key + 1).lastLongKey()} to find the
+     * floor key, then constructs an entry with that key and its associated value.
+     *
+     * <p><b>Edge cases:</b>
+     * <ul>
+     *   <li>If {@code key} equals {@link Long#MAX_VALUE}, {@code key + 1} overflows
+     *       to {@link Long#MIN_VALUE}. In this case we fall back to checking the
+     *       entire map's last key.</li>
+     *   <li>If the map is empty or all keys are greater than {@code key}, returns
+     *       {@code null}.</li>
+     * </ul>
+     *
+     * @param key the key to search for
+     * @return an entry with the greatest key ≤ {@code key}, or {@code null}
+     */
+    public Long2ShortMap.Entry floorEntry(long key) {
+        if (isEmpty()) {
+            return null;
+        }
+
+        // Handle Long.MAX_VALUE overflow: key + 1 wraps to Long.MIN_VALUE
+        if (key == Long.MAX_VALUE) {
+            // If key is MAX_VALUE, floor is the map's last key (if it exists)
+            long lastKey = lastLongKey();
+            return new BasicEntry(lastKey, get(lastKey));
+        }
+
+        // headMap(toKey) returns keys strictly < toKey
+        // So headMap(key + 1) returns keys ≤ key
+        Long2ShortSortedMap head = headMap(key + 1);
+
+        if (head.isEmpty()) {
+            return null;
+        }
+
+        long floorKey = head.lastLongKey();
+        return new BasicEntry(floorKey, get(floorKey));
+    }
+}