update the nodes to the new API

Author: triceo

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

@@ -16,6 +16,6 @@ public interface BiConstraintCollectorAccumulator<ResultContainer_, A, B> {
      * As defined by {@link UniConstraintCollectorAccumulator#intoGroup(Object)},
      * only for {@link BiConstraintCollector}.
      */
-    BiConstraintCollectorAccumulatedValue<A, B> startGroup(ResultContainer_ resultContainer);
+    BiConstraintCollectorAccumulatedValue<A, B> intoGroup(ResultContainer_ resultContainer);
 
 }

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

@@ -16,6 +16,6 @@ public interface QuadConstraintCollectorAccumulator<ResultContainer_, A, B, C, D
      * As defined by {@link UniConstraintCollectorAccumulator#intoGroup(Object)},
      * only for {@link QuadConstraintCollector}.
      */
-    QuadConstraintCollectorAccumulatedValue<A, B, C, D> startGroup(ResultContainer_ resultContainer);
+    QuadConstraintCollectorAccumulatedValue<A, B, C, D> intoGroup(ResultContainer_ resultContainer);
 
 }

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

@@ -16,6 +16,6 @@ public interface TriConstraintCollectorAccumulator<ResultContainer_, A, B, C> {
      * As defined by {@link UniConstraintCollectorAccumulator#intoGroup(Object)},
      * only for {@link TriConstraintCollector}.
      */
-    TriConstraintCollectorAccumulatedValue<A, B, C> startGroup(ResultContainer_ resultContainer);
+    TriConstraintCollectorAccumulatedValue<A, B, C> intoGroup(ResultContainer_ resultContainer);
 
 }

core/src/main/java/ai/timefold/solver/core/impl/bavet/bi/AbstractGroupBiNode.java

@@ -17,12 +17,12 @@
 abstract class AbstractGroupBiNode<OldA, OldB, OutTuple_ extends Tuple, GroupKey_, ResultContainer_, Result_>
         extends AbstractGroupNode<BiTuple<OldA, OldB>, OutTuple_, GroupKey_, ResultContainer_, Result_> {
 
-    private final int undoStoreIndex;
+    private final int groupAccumulatorIndex;
     private final @Nullable TriFunction<ResultContainer_, OldA, OldB, Runnable> accumulator;
     private final @Nullable BiConstraintCollectorAccumulator<ResultContainer_, OldA, OldB> incrementalAccumulator;
     private final boolean useIncrementalAccumulator;
 
-    protected AbstractGroupBiNode(int groupStoreIndex, int undoStoreIndex,
+    protected AbstractGroupBiNode(int groupStoreIndex, int groupAccumulatorIndex,
             Function<BiTuple<OldA, OldB>, GroupKey_> groupKeyFunction,
             BiConstraintCollector<OldA, OldB, ResultContainer_, Result_> collector,
             TupleLifecycle<OutTuple_> nextNodesTupleLifecycle, EnvironmentMode environmentMode) {
@@ -31,7 +31,7 @@ protected AbstractGroupBiNode(int groupStoreIndex, int undoStoreIndex,
                 collector == null ? null : collector.finisher(),
                 nextNodesTupleLifecycle, environmentMode);
         var hasCollector = collector != null;
-        this.undoStoreIndex = hasCollector ? undoStoreIndex : -1;
+        this.groupAccumulatorIndex = hasCollector ? groupAccumulatorIndex : -1;
         accumulator = hasCollector ? (collector.isIncremental() ? null : collector.accumulator()) : null;
         incrementalAccumulator = hasCollector ? (collector.isIncremental() ? collector.incrementalAccumulator() : null) : null;
         useIncrementalAccumulator = hasCollector && incrementalAccumulator != null;
@@ -40,42 +40,43 @@ protected AbstractGroupBiNode(int groupStoreIndex, int undoStoreIndex,
     protected AbstractGroupBiNode(int groupStoreIndex, Function<BiTuple<OldA, OldB>, GroupKey_> groupKeyFunction,
             TupleLifecycle<OutTuple_> nextNodesTupleLifecycle, EnvironmentMode environmentMode) {
         super(groupStoreIndex, groupKeyFunction, nextNodesTupleLifecycle, environmentMode);
-        undoStoreIndex = -1;
+        groupAccumulatorIndex = -1;
         accumulator = null;
         incrementalAccumulator = null;
         useIncrementalAccumulator = false;
     }
 
     @Override
-    protected void groupInsert(ResultContainer_ resultContainer, BiTuple<OldA, OldB> tuple) {
+    protected boolean groupInsert(ResultContainer_ resultContainer, BiTuple<OldA, OldB> tuple) {
         if (useIncrementalAccumulator) {
-            var undoAccumulator = incrementalAccumulator.startGroup(resultContainer);
-            undoAccumulator.add(tuple.getA(), tuple.getB());
-            tuple.setStore(undoStoreIndex, undoAccumulator);
+            var groupContents = incrementalAccumulator.intoGroup(resultContainer);
+            tuple.setStore(groupAccumulatorIndex, groupContents);
+            return groupContents.add(tuple.getA(), tuple.getB());
         } else {
-            var undoAccumulator = accumulator.apply(resultContainer, tuple.getA(), tuple.getB());
-            tuple.setStore(undoStoreIndex, undoAccumulator);
+            tuple.setStore(groupAccumulatorIndex, accumulator.apply(resultContainer, tuple.getA(), tuple.getB()));
+            return true;
         }
     }
 
     @Override
     protected boolean groupUpdate(ResultContainer_ resultContainer, BiTuple<OldA, OldB> tuple) {
         if (useIncrementalAccumulator) {
-            BiConstraintCollectorAccumulatedValue<OldA, OldB> undoAccumulator = tuple.getStore(undoStoreIndex);
-            return undoAccumulator.update(tuple.getA(), tuple.getB());
+            BiConstraintCollectorAccumulatedValue<OldA, OldB> groupContents = tuple.getStore(groupAccumulatorIndex);
+            return groupContents.update(tuple.getA(), tuple.getB());
         } else {
             return super.groupUpdate(resultContainer, tuple);
         }
     }
 
     @Override
-    protected void groupRetract(ResultContainer_ resultContainer, BiTuple<OldA, OldB> tuple) {
+    protected boolean groupRetract(BiTuple<OldA, OldB> tuple) {
         if (useIncrementalAccumulator) {
-            BiConstraintCollectorAccumulatedValue<OldA, OldB> undoAccumulator = tuple.removeStore(undoStoreIndex);
-            undoAccumulator.remove();
+            BiConstraintCollectorAccumulatedValue<OldA, OldB> groupContents = tuple.removeStore(groupAccumulatorIndex);
+            return groupContents.remove();
         } else {
-            Runnable undoAccumulator = tuple.removeStore(undoStoreIndex);
-            undoAccumulator.run();
+            Runnable undo = tuple.removeStore(groupAccumulatorIndex);
+            undo.run();
+            return true;
         }
     }
 }

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

@@ -53,9 +53,9 @@ public abstract class AbstractGroupNode<InTuple_ extends Tuple, OutTuple_ extend
     private final boolean useAssertingGroupKey;
 
     protected AbstractGroupNode(int groupStoreIndex, Function<InTuple_, GroupKey_> groupKeyFunction,
-            Supplier<ResultContainer_> supplier,
-            Function<ResultContainer_, Result_> finisher,
-            TupleLifecycle<OutTuple_> nextNodesTupleLifecycle, EnvironmentMode environmentMode) {
+                                Supplier<ResultContainer_> supplier,
+                                Function<ResultContainer_, Result_> finisher,
+                                TupleLifecycle<OutTuple_> nextNodesTupleLifecycle, EnvironmentMode environmentMode) {
         this.groupStoreIndex = groupStoreIndex;
         this.groupKeyFunction = groupKeyFunction;
         this.supplier = supplier;
@@ -80,8 +80,8 @@ protected AbstractGroupNode(int groupStoreIndex, Function<InTuple_, GroupKey_> g
     }
 
     protected AbstractGroupNode(int groupStoreIndex,
-            Function<InTuple_, GroupKey_> groupKeyFunction, TupleLifecycle<OutTuple_> nextNodesTupleLifecycle,
-            EnvironmentMode environmentMode) {
+                                Function<InTuple_, GroupKey_> groupKeyFunction, TupleLifecycle<OutTuple_> nextNodesTupleLifecycle,
+                                EnvironmentMode environmentMode) {
         this(groupStoreIndex,
                 groupKeyFunction, null, null, nextNodesTupleLifecycle,
                 environmentMode);
@@ -95,33 +95,35 @@ public StreamKind getStreamKind() {
     @Override
     public final void insert(InTuple_ tuple) {
         if (tuple.getStore(groupStoreIndex) != null) {
-            throw new IllegalStateException("Impossible state: the input for the tuple (" + tuple
-                    + ") was already added in the tupleStore.");
+            throw new IllegalStateException(
+                    "Impossible state: the input for the tuple (%s) was already added in the tupleStore."
+                            .formatted(tuple));
         }
         var userSuppliedKey = hasMultipleGroups ? groupKeyFunction.apply(tuple) : null;
         createTuple(tuple, userSuppliedKey);
     }
 
     private void createTuple(InTuple_ tuple, GroupKey_ userSuppliedKey) {
-        var newGroup = getOrCreateGroup(userSuppliedKey);
-        var outTuple = accumulate(tuple, newGroup);
+        var group = getOrCreateGroup(userSuppliedKey);
+        var needsPropagation = group.parentCount == 1; // Fresh outTuple.
+        if (hasCollector) {
+            needsPropagation = groupInsert(group.getResultContainer(), tuple) || needsPropagation;
+        }
+        tuple.setStore(groupStoreIndex, group);
+        if (!needsPropagation) {
+            return;
+        }
+        var outTuple = group.getTuple();
         switch (outTuple.getState()) {
             case CREATING, UPDATING -> {
                 // Already in the correct state.
             }
-            case OK, DYING -> propagationQueue.update(newGroup);
-            case ABORTING -> propagationQueue.insert(newGroup);
-            default -> throw new IllegalStateException("Impossible state: The group (" + newGroup + ") in node (" + this
-                    + ") is in an unexpected state (" + outTuple.getState() + ").");
-        }
-    }
-
-    private OutTuple_ accumulate(InTuple_ tuple, Group<OutTuple_, ResultContainer_> group) {
-        if (hasCollector) {
-            groupInsert(group.getResultContainer(), tuple);
+            case OK, DYING -> propagationQueue.update(group);
+            case ABORTING -> propagationQueue.insert(group);
+            default -> throw new IllegalStateException(
+                    "Impossible state: The group (%s) in node (%s) is in an unexpected state (%s)."
+                            .formatted(group, this, outTuple.getState()));
         }
-        tuple.setStore(groupStoreIndex, group);
-        return group.getTuple();
     }
 
     private Group<OutTuple_, ResultContainer_> getOrCreateGroup(GroupKey_ userSuppliedKey) {
@@ -150,16 +152,17 @@ private Group<OutTuple_, ResultContainer_> createGroupWithGroupKey(Object groupM
         var userSuppliedKey = extractUserSuppliedKey(groupMapKey);
         var outTuple = createOutTuple(userSuppliedKey);
         var group = hasCollector ? Group.create(groupMapKey, supplier.get(), outTuple)
-                : Group.<OutTuple_, ResultContainer_> createWithoutAccumulate(groupMapKey, outTuple);
+                : Group.<OutTuple_, ResultContainer_>createWithoutAccumulate(groupMapKey, outTuple);
         propagationQueue.insert(group);
         return group;
     }
 
     private Group<OutTuple_, ResultContainer_> createGroupWithoutGroupKey() {
         var outTuple = createOutTuple(null);
         if (!hasCollector) {
-            throw new IllegalStateException("Impossible state: The node (" + this + ") has no collector, "
-                    + "but it is still trying to create a group without a group key.");
+            throw new IllegalStateException(
+                    "Impossible state: The node (%s) has no collector, but it is still trying to create a group without a group key."
+                            .formatted(this));
         }
         var group = Group.createWithoutGroupKey(supplier.get(), outTuple);
         propagationQueue.insert(group);
@@ -188,10 +191,12 @@ public final void update(InTuple_ tuple) {
         if (Objects.equals(oldUserSuppliedGroupKey, newUserSuppliedGroupKey)) {
             updateGroup(tuple, oldGroup);
         } else {
+            var needsPropagation = false;
             if (hasCollector) {
-                groupRetract(oldGroup.getResultContainer(), tuple);
+                needsPropagation = groupRetract(tuple);
             }
-            killTuple(oldGroup);
+            var newParentCount = --oldGroup.parentCount;
+            killOutTuple(oldGroup, newParentCount == 0, needsPropagation);
             createTuple(tuple, newUserSuppliedGroupKey);
         }
     }
@@ -204,28 +209,38 @@ private void updateGroup(InTuple_ tuple, Group<OutTuple_, ResultContainer_> oldG
                 return;
             }
         }
+        // TODO if it has no collectors, maybe skip the propagation?
         var outTuple = oldGroup.getTuple();
         switch (outTuple.getState()) {
             case CREATING, UPDATING -> {
                 // Already in the correct state.
             }
             case OK -> propagationQueue.update(oldGroup);
-            default ->
-                throw new IllegalStateException("Impossible state: The group (%s) in node (%s) is in an unexpected state (%s)."
-                        .formatted(oldGroup, this, outTuple.getState()));
+            default -> throw new IllegalStateException(
+                    "Impossible state: The group (%s) in node (%s) is in an unexpected state (%s)."
+                            .formatted(oldGroup, this, outTuple.getState()));
         }
     }
 
-    private void killTuple(Group<OutTuple_, ResultContainer_> group) {
-        var newParentCount = --group.parentCount;
-        var killGroup = (newParentCount == 0);
+    /**
+     *
+     * @param group the group which created the outTuple
+     * @param killGroup true if the group should be removed from downstream nodes
+     * @param propagateUpdate may be true while killGroup is also true;
+     *        propagating updates is irrelevant if the group is already being killed
+     */
+    private void killOutTuple(Group<OutTuple_, ResultContainer_> group, boolean killGroup, boolean propagateUpdate) {
+        if (!killGroup && !propagateUpdate) { // Nothing has changed.
+            return;
+        }
         if (killGroup) {
             var groupKey = hasMultipleGroups ? group.getGroupKey() : null;
             var oldGroup = removeGroup(groupKey);
             if (oldGroup == null) {
-                throw new IllegalStateException("Impossible state: the group for the groupKey ("
-                        + groupKey + ") doesn't exist in the groupMap.\n" +
-                        "Maybe groupKey hashcode changed while it shouldn't have?");
+                throw new IllegalStateException("""
+                        Impossible state: the group for the groupKey (%s) doesn't exist in the groupMap.
+                        Maybe groupKey hashcode changed while it shouldn't have?"""
+                        .formatted(groupKey));
             }
         }
         var outTuple = group.getTuple();
@@ -247,8 +262,9 @@ private void killTuple(Group<OutTuple_, ResultContainer_> group) {
                     propagationQueue.update(group);
                 }
             }
-            default -> throw new IllegalStateException("Impossible state: The group (" + group + ") in node (" + this
-                    + ") is in an unexpected state (" + outTuple.getState() + ").");
+            default -> throw new IllegalStateException(
+                    "Impossible state: The group (%s) in node (%s) is in an unexpected state (%s)."
+                            .formatted(group, this, outTuple.getState()));
         }
     }
 
@@ -269,21 +285,23 @@ public final void retract(InTuple_ tuple) {
             // No fail fast if null because we don't track which tuples made it through the filter predicate(s)
             return;
         }
+        var needsPropagation = false;
         if (hasCollector) {
-            groupRetract(group.getResultContainer(), tuple);
+            needsPropagation = groupRetract(tuple);
         }
-        killTuple(group);
+        var newParentCount = --group.parentCount;
+        killOutTuple(group, newParentCount == 0, needsPropagation);
     }
 
-    protected abstract void groupInsert(ResultContainer_ resultContainer, InTuple_ tuple);
+    protected abstract boolean groupInsert(ResultContainer_ resultContainer, InTuple_ tuple);
 
     protected boolean groupUpdate(ResultContainer_ resultContainer, InTuple_ tuple) {
-        groupRetract(resultContainer, tuple);
-        groupInsert(resultContainer, tuple);
-        return true;
+        var retractNeedsPropagation = groupRetract(tuple);
+        var insertNeedsPropagation = groupInsert(resultContainer, tuple);
+        return retractNeedsPropagation || insertNeedsPropagation;
     }
 
-    protected abstract void groupRetract(ResultContainer_ resultContainer, InTuple_ tuple);
+    protected abstract boolean groupRetract(InTuple_ tuple);
 
     @Override
     public Propagator getPropagator() {