perf: improve ConstraintCollectors.toList() (#2285)

The underlying collection is now optimized for removals, as those operations will be frequent inside group nodes. It still retains fast random access to elements, as that is required to reuse it in Neighborhoods.

The collection supports null values, and implements the full list interface; this makes it a suitable replacement to ArrayList.

Compared to ArrayList, remove() is super-fast if done via the entry. This introduces small overhead in addition and iteration, as the arrays may need to be compacted. Some operations compare equally poorly in both collections, such as additions into the middle of the array.

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/impl/bavet/common/AbstractIndexedIfExistsNode.java

@@ -119,8 +119,9 @@ public final void retractLeft(LeftTuple_ leftTuple) {
             return;
         }
         ListEntry<ExistsCounter<LeftTuple_>> counterEntry = leftTuple.getStore(inputStoreIndexLeftCounterEntry);
+        var element = counterEntry.element(); // Store so that the reference survives removal.
         updateIndexerLeft(compositeKey, counterEntry, leftTuple);
-        killCounterLeft(counterEntry.element());
+        killCounterLeft(element);
     }
 
     private void updateIndexerLeft(Object compositeKey, ListEntry<ExistsCounter<LeftTuple_>> counterEntry,

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,12 +24,12 @@ 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
     public void remove(Object compositeKey, ListEntry<T> entry) {
-        tupleList.remove((ElementAwareArrayList.Entry<T>) entry);
+        ((ElementAwareArrayList<T>.Entry) entry).remove();
     }
 
     @Override

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

@@ -6,7 +6,6 @@
 import ai.timefold.solver.core.impl.bavet.common.index.UniqueRandomIterator;
 import ai.timefold.solver.core.impl.bavet.common.tuple.Tuple;
 import ai.timefold.solver.core.impl.util.ElementAwareArrayList;
-import ai.timefold.solver.core.impl.util.ElementAwareArrayList.Entry;
 
 import org.jspecify.annotations.NullMarked;
 
@@ -35,7 +34,7 @@ public void insert(Tuple_ tuple) {
                             .formatted(tuple));
         }
 
-        tuple.setStore(entryStoreIndex, tupleList.add(tuple));
+        tuple.setStore(entryStoreIndex, tupleList.addEntry(tuple));
     }
 
     @Override
@@ -50,13 +49,12 @@ public void update(Tuple_ tuple) {
 
     @Override
     public void retract(Tuple_ tuple) {
-        Entry<Tuple_> entry = tuple.removeStore(entryStoreIndex);
+        ElementAwareArrayList<Tuple_>.Entry entry = tuple.removeStore(entryStoreIndex);
         if (entry == null) {
             // No fail fast if null because we don't track which tuples made it through the filter predicate(s)
             return;
         }
-
-        tupleList.remove(entry);
+        entry.remove();
     }
 
     @Override

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

@@ -1,15 +1,21 @@
 package ai.timefold.solver.core.impl.score.stream.collector;
 
-import java.util.ArrayList;
 import java.util.List;
 
+import ai.timefold.solver.core.impl.util.ElementAwareArrayList;
+
 public final class ListUndoableActionable<Mapped_> implements UndoableActionable<Mapped_, List<Mapped_>> {
-    private final List<Mapped_> resultList = new ArrayList<>();
+
+    /**
+     * As long as additions and removals are performed using entry-based methods,
+     * removals have O(1) performance.
+     */
+    private final ElementAwareArrayList<Mapped_> resultList = new ElementAwareArrayList<>();
 
     @Override
     public Runnable insert(Mapped_ result) {
-        resultList.add(result);
-        return () -> resultList.remove(result);
+        var entry = resultList.addEntry(result);
+        return entry::remove;
     }
 
     @Override