Another wave

Author: triceo

core/src/main/java/ai/timefold/solver/core/api/score/stream/ConstraintCollectors.java

@@ -767,6 +767,7 @@ public final class ConstraintCollectors {
      * For stable iteration order, use {@link #toSortedSet()}.
      * <p>
      * The default result of the collector (e.g. when never called) is an empty {@link Set}.
+     * The user must not modify this set.
      *
      * @param <A> type of the matched fact
      */
@@ -779,6 +780,7 @@ public final class ConstraintCollectors {
      * {@link ConstraintStream}.
      * <p>
      * The default result of the collector (e.g. when never called) is an empty {@link SortedSet}.
+     * The user must not modify this set.
      *
      * @param <A> type of the matched fact
      */
@@ -800,6 +802,7 @@ public final class ConstraintCollectors {
      * For stable iteration order, use {@link #toSortedSet()}.
      * <p>
      * The default result of the collector (e.g. when never called) is an empty {@link List}.
+     * The user must not modify this list.
      *
      * @param <A> type of the matched fact
      */
@@ -976,6 +979,7 @@ public final class ConstraintCollectors {
      * For stable iteration order, use {@link #toSortedMap(Function, Function, IntFunction)}.
      * <p>
      * The default result of the collector (e.g. when never called) is an empty {@link Map}.
+     * The user must not modify this map.
      *
      * @param keyMapper map matched fact to a map key
      * @param valueMapper map matched fact to a value
@@ -1103,6 +1107,7 @@ public final class ConstraintCollectors {
      * {@code {20: "Ann and Eric", 25: "Beth", 30: "Cathy and David"}}.
      * <p>
      * The default result of the collector (e.g. when never called) is an empty {@link SortedMap}.
+     * The user must not modify this map.
      *
      * @param keyMapper map matched fact to a map key
      * @param valueMapper map matched fact to a value

core/src/main/java/ai/timefold/solver/core/api/score/stream/uni/UniConstraintCollectorAccumulator.java

@@ -23,8 +23,8 @@ public interface UniConstraintCollectorAccumulator<ResultContainer_, A> {
      *        {@link UniConstraintCollector#supplier()} will be used to supply a fresh instance of the container;
      *        otherwise a pre-existing container will be used, carrying the accumulated state.
      *        {@link UniConstraintCollector#finisher()} will be used to extract the final accumulated value from the container.
-     *        The container is the only state that the accumulator may rely on;
-     *        any other state will result in subtle score corruption issues.
+     *        The accumulator factory itself must not hold mutable cross-slot state;
+     *        any mutable state must live in the container or in the returned accumulated value.
      * @return the accumulator for the value, which will be used to insert the value to the group,
      *         to update it while in the group, and to remove it from the group.
      */

core/src/main/java/ai/timefold/solver/core/impl/bavet/common/index/DefaultUniqueRandomIterator.java

@@ -59,7 +59,7 @@ public boolean hasNext() {
         if (nextIndex == -1) {
             return false;
         }
-        next = source.get(nextIndex).element();
+        next = source.get(nextIndex);
         indexToOptionallyRemove = -1;
         return true;
     }

core/src/main/java/ai/timefold/solver/core/impl/bavet/common/index/RandomAccessIndexerBackend.java

@@ -24,7 +24,7 @@ public final class RandomAccessIndexerBackend<T> implements IndexerBackend<T> {
 
     @Override
     public ListEntry<T> put(Object compositeKey, T tuple) {
-        return tupleList.add(tuple);
+        return tupleList.addEntry(tuple);
     }
 
     @Override

core/src/main/java/ai/timefold/solver/core/impl/neighborhood/stream/enumerating/common/AbstractLeftDatasetInstance.java

@@ -35,7 +35,7 @@ public void insert(Tuple_ tuple) {
                             .formatted(tuple));
         }
 
-        tuple.setStore(entryStoreIndex, tupleList.add(tuple));
+        tuple.setStore(entryStoreIndex, tupleList.addEntry(tuple));
     }
 
     @Override

…collector/ConnectedRangesCalculator.java …llector/AbstractConnectedRangesSlot.javacore/src/main/java/ai/timefold/solver/core/impl/score/stream/collector/ConnectedRangesCalculator.java renamed to core/src/main/java/ai/timefold/solver/core/impl/score/stream/collector/AbstractConnectedRangesSlot.java core/src/main/java/ai/timefold/solver/core/impl/score/stream/collector/ConnectedRangesCalculator.java renamed to core/src/main/java/ai/timefold/solver/core/impl/score/stream/collector/AbstractConnectedRangesSlot.java

@@ -7,8 +7,7 @@
 import ai.timefold.solver.core.impl.score.stream.collector.connected_ranges.ConnectedRangeTracker;
 import ai.timefold.solver.core.impl.score.stream.collector.connected_ranges.Range;
 
-public final class ConnectedRangesCalculator<Interval_, Point_ extends Comparable<Point_>, Difference_ extends Comparable<Difference_>>
-        implements ObjectCalculator<Interval_> {
+public abstract class AbstractConnectedRangesSlot<Interval_, Point_ extends Comparable<Point_>, Difference_ extends Comparable<Difference_>> {
 
     public static final class State<Interval_, Point_ extends Comparable<Point_>, Difference_ extends Comparable<Difference_>> {
         private final ConnectedRangeTracker<Interval_, Point_, Difference_> context;
@@ -27,26 +26,23 @@ public ConnectedRangeChain<Interval_, Point_, Difference_> result() {
     private final State<Interval_, Point_, Difference_> state;
     private Range<Interval_, Point_> cachedRange;
 
-    public ConnectedRangesCalculator(State<Interval_, Point_, Difference_> state) {
+    public AbstractConnectedRangesSlot(State<Interval_, Point_, Difference_> state) {
         this.state = state;
     }
 
-    @Override
-    public void insert(Interval_ result) {
+    protected void addMapped(Interval_ result) {
         final var saved = state.context.getRange(result);
         cachedRange = saved;
         state.context.add(saved);
     }
 
-    @Override
-    public void update(Interval_ input) {
+    protected void updateMapped(Interval_ input) {
         state.context.remove(cachedRange);
         cachedRange = state.context.getRange(input);
         state.context.add(cachedRange);
     }
 
-    @Override
-    public void retract() {
+    protected void removeMapped() {
         state.context.remove(cachedRange);
     }
 }

core/src/main/java/ai/timefold/solver/core/impl/score/stream/collector/AbstractCountSlot.java

@@ -0,0 +1,30 @@
+package ai.timefold.solver.core.impl.score.stream.collector;
+
+public abstract class AbstractCountSlot {
+
+    public static final class State {
+        long count = 0;
+
+        public Long result() {
+            return count;
+        }
+    }
+
+    private final State state;
+
+    public AbstractCountSlot(State state) {
+        this.state = state;
+    }
+
+    protected void addMapped() {
+        state.count++;
+    }
+
+    protected void updateMapped() {
+        // count unchanged on update
+    }
+
+    protected void removeMapped() {
+        state.count--;
+    }
+}

core/src/main/java/ai/timefold/solver/core/impl/score/stream/collector/AbstractLoadBalanceSlot.java

@@ -0,0 +1,34 @@
+package ai.timefold.solver.core.impl.score.stream.collector;
+
+import java.util.Objects;
+
+import org.jspecify.annotations.Nullable;
+
+public abstract class AbstractLoadBalanceSlot<Balanced_> {
+
+    private final DefaultLoadBalance<Balanced_> container;
+    private @Nullable Balanced_ cachedBalanced;
+    private long cachedLoad;
+
+    public AbstractLoadBalanceSlot(DefaultLoadBalance<Balanced_> container) {
+        this.container = container;
+    }
+
+    protected void addMapped(Balanced_ balanced, long load, long initialLoad) {
+        cachedBalanced = balanced;
+        cachedLoad = load;
+        container.registerBalanced(balanced, load, initialLoad);
+    }
+
+    protected void updateMapped(Balanced_ balanced, long load, long initialLoad) {
+        if (Objects.equals(cachedBalanced, balanced) && cachedLoad == load) {
+            return;
+        }
+        removeMapped();
+        addMapped(balanced, load, initialLoad);
+    }
+
+    protected void removeMapped() {
+        container.unregisterBalanced(cachedBalanced, cachedLoad);
+    }
+}

…eam/collector/LongAverageCalculator.java …m/collector/AbstractLongAverageSlot.javacore/src/main/java/ai/timefold/solver/core/impl/score/stream/collector/LongAverageCalculator.java renamed to core/src/main/java/ai/timefold/solver/core/impl/score/stream/collector/AbstractLongAverageSlot.java core/src/main/java/ai/timefold/solver/core/impl/score/stream/collector/LongAverageCalculator.java renamed to core/src/main/java/ai/timefold/solver/core/impl/score/stream/collector/AbstractLongAverageSlot.java

@@ -1,6 +1,6 @@
 package ai.timefold.solver.core.impl.score.stream.collector;
 
-public final class LongAverageCalculator implements LongCalculator {
+public abstract class AbstractLongAverageSlot {
 
     public static final class State {
         long count = 0;
@@ -17,25 +17,22 @@ public Double result() {
     private final State state;
     private long cachedInput;
 
-    public LongAverageCalculator(State state) {
+    public AbstractLongAverageSlot(State state) {
         this.state = state;
     }
 
-    @Override
-    public void insert(long input) {
+    protected void addMapped(long input) {
         cachedInput = input;
         state.count++;
         state.sum += input;
     }
 
-    @Override
-    public void update(long input) {
+    protected void updateMapped(long input) {
         state.sum += input - cachedInput;
         cachedInput = input;
     }
 
-    @Override
-    public void retract() {
+    protected void removeMapped() {
         state.count--;
         state.sum -= cachedInput;
     }

…llector/LongDistinctCountCalculator.java …/collector/AbstractLongDistinctSlot.javacore/src/main/java/ai/timefold/solver/core/impl/score/stream/collector/LongDistinctCountCalculator.java renamed to core/src/main/java/ai/timefold/solver/core/impl/score/stream/collector/AbstractLongDistinctSlot.java core/src/main/java/ai/timefold/solver/core/impl/score/stream/collector/LongDistinctCountCalculator.java renamed to core/src/main/java/ai/timefold/solver/core/impl/score/stream/collector/AbstractLongDistinctSlot.java

@@ -8,7 +8,7 @@
 
 import org.jspecify.annotations.Nullable;
 
-public final class LongDistinctCountCalculator<Input_> implements ObjectCalculator<Input_> {
+public abstract class AbstractLongDistinctSlot<Input_> {
 
     public static final class State<Input_> {
         private final Map<Input_, MutableInt> countMap = new HashMap<>();
@@ -22,28 +22,25 @@ public Long result() {
     private @Nullable Input_ cachedInput;
     private @Nullable MutableInt cachedCounter;
 
-    public LongDistinctCountCalculator(State<Input_> state) {
+    public AbstractLongDistinctSlot(State<Input_> state) {
         this.state = state;
     }
 
-    @Override
-    public void insert(Input_ input) {
+    protected void addMapped(Input_ input) {
         cachedInput = input;
         cachedCounter = state.countMap.computeIfAbsent(input, ignored -> new MutableInt());
         cachedCounter.increment();
     }
 
-    @Override
-    public void update(Input_ input) {
+    protected void updateMapped(Input_ input) {
         if (Objects.equals(cachedInput, input)) {
             return;
         }
-        retract();
-        insert(input);
+        removeMapped();
+        addMapped(input);
     }
 
-    @Override
-    public void retract() {
+    protected void removeMapped() {
         if (cachedCounter.decrement() == 0) {
             state.countMap.remove(cachedInput);
         }