chore: filtering move selector enforcing the phase termination

Author: zepfred

core/src/main/java/ai/timefold/solver/core/impl/heuristic/selector/move/decorator/FilteringMoveSelector.java

@@ -9,6 +9,7 @@
 import ai.timefold.solver.core.impl.heuristic.selector.move.AbstractMoveSelector;
 import ai.timefold.solver.core.impl.heuristic.selector.move.MoveSelector;
 import ai.timefold.solver.core.impl.phase.scope.AbstractPhaseScope;
+import ai.timefold.solver.core.impl.solver.termination.PhaseTermination;
 
 public final class FilteringMoveSelector<Solution_> extends AbstractMoveSelector<Solution_> {
 
@@ -24,6 +25,7 @@ public static <Solution_> FilteringMoveSelector<Solution_> of(MoveSelector<Solut
     private final MoveSelector<Solution_> childMoveSelector;
     private final SelectionFilter<Solution_, Move<Solution_>> filter;
     private final boolean bailOutEnabled;
+    private AbstractPhaseScope<Solution_> phaseScope;
 
     private ScoreDirector<Solution_> scoreDirector = null;
 
@@ -42,13 +44,15 @@ private FilteringMoveSelector(MoveSelector<Solution_> childMoveSelector,
     @Override
     public void phaseStarted(AbstractPhaseScope<Solution_> phaseScope) {
         super.phaseStarted(phaseScope);
-        scoreDirector = phaseScope.getScoreDirector();
+        this.scoreDirector = phaseScope.getScoreDirector();
+        this.phaseScope = phaseScope;
     }
 
     @Override
     public void phaseEnded(AbstractPhaseScope<Solution_> phaseScope) {
         super.phaseEnded(phaseScope);
-        scoreDirector = null;
+        this.scoreDirector = null;
+        this.phaseScope = null;
     }
 
     @Override
@@ -68,17 +72,22 @@ public long getSize() {
 
     @Override
     public Iterator<Move<Solution_>> iterator() {
-        return new JustInTimeFilteringMoveIterator(childMoveSelector.iterator(), determineBailOutSize());
+        return new JustInTimeFilteringMoveIterator(childMoveSelector.iterator(), determineBailOutSize(), phaseScope);
     }
 
     private class JustInTimeFilteringMoveIterator extends UpcomingSelectionIterator<Move<Solution_>> {
 
         private final Iterator<Move<Solution_>> childMoveIterator;
         private final long bailOutSize;
+        private final AbstractPhaseScope<Solution_> phaseScope;
+        private final PhaseTermination<Solution_> termination;
 
-        public JustInTimeFilteringMoveIterator(Iterator<Move<Solution_>> childMoveIterator, long bailOutSize) {
+        public JustInTimeFilteringMoveIterator(Iterator<Move<Solution_>> childMoveIterator, long bailOutSize,
+                AbstractPhaseScope<Solution_> phaseScope) {
             this.childMoveIterator = childMoveIterator;
             this.bailOutSize = bailOutSize;
+            this.phaseScope = phaseScope;
+            this.termination = phaseScope.getTermination();
         }
 
         @Override
@@ -95,6 +104,11 @@ protected Move<Solution_> createUpcomingSelection() {
                         logger.trace("Bailing out of neverEnding selector ({}) after ({}) attempts to avoid infinite loop.",
                                 FilteringMoveSelector.this, bailOutSize);
                         return noUpcomingSelection();
+                    } else if (termination != null && termination.isPhaseTerminated(phaseScope)) {
+                        logger.trace(
+                                "Bailing out of neverEnding selector ({}) because the termination setting has been triggered.",
+                                FilteringMoveSelector.this);
+                        return noUpcomingSelection();
                     }
                     attemptsBeforeBailOut--;
                 }

core/src/main/java/ai/timefold/solver/core/impl/localsearch/DefaultLocalSearchPhase.java

@@ -125,6 +125,7 @@ public void phaseStarted(LocalSearchPhaseScope<Solution_> phaseScope) {
         super.phaseStarted(phaseScope);
         decider.phaseStarted(phaseScope);
         assertWorkingSolutionInitialized(phaseScope);
+        phaseScope.setTermination(phaseTermination);
     }
 
     @Override

core/src/main/java/ai/timefold/solver/core/impl/phase/scope/AbstractPhaseScope.java

@@ -9,6 +9,7 @@
 import ai.timefold.solver.core.impl.score.director.InnerScore;
 import ai.timefold.solver.core.impl.score.director.InnerScoreDirector;
 import ai.timefold.solver.core.impl.solver.scope.SolverScope;
+import ai.timefold.solver.core.impl.solver.termination.PhaseTermination;
 import ai.timefold.solver.core.preview.api.move.Move;
 
 import org.slf4j.Logger;
@@ -36,6 +37,11 @@ public abstract class AbstractPhaseScope<Solution_> {
 
     protected int bestSolutionStepIndex;
 
+    /**
+     * The solver termination configuration
+     */
+    private PhaseTermination<Solution_> termination;
+
     /**
      * As defined by #AbstractPhaseScope(SolverScope, int, boolean)
      * with the phaseSendingBestSolutionEvents parameter set to true.
@@ -188,6 +194,14 @@ public <Score_ extends Score<Score_>> InnerScoreDirector<Solution_, Score_> getS
         return solverScope.getScoreDirector();
     }
 
+    public void setTermination(PhaseTermination<Solution_> termination) {
+        this.termination = termination;
+    }
+
+    public PhaseTermination<Solution_> getTermination() {
+        return termination;
+    }
+
     public Solution_ getWorkingSolution() {
         return solverScope.getWorkingSolution();
     }

core/src/test/java/ai/timefold/solver/core/impl/heuristic/selector/move/decorator/FilteringMoveSelectorTest.java

@@ -2,11 +2,15 @@
 
 import static ai.timefold.solver.core.testutil.PlannerAssert.assertAllCodesOfMoveSelector;
 import static ai.timefold.solver.core.testutil.PlannerAssert.verifyPhaseLifecycle;
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.ArgumentMatchers.any;
 import static org.mockito.Mockito.mock;
 import static org.mockito.Mockito.times;
 import static org.mockito.Mockito.verify;
 import static org.mockito.Mockito.when;
 
+import java.util.Iterator;
+
 import ai.timefold.solver.core.config.heuristic.selector.common.SelectionCacheType;
 import ai.timefold.solver.core.impl.heuristic.move.DummyMove;
 import ai.timefold.solver.core.impl.heuristic.selector.SelectorTestUtils;
@@ -15,6 +19,7 @@
 import ai.timefold.solver.core.impl.phase.scope.AbstractPhaseScope;
 import ai.timefold.solver.core.impl.phase.scope.AbstractStepScope;
 import ai.timefold.solver.core.impl.solver.scope.SolverScope;
+import ai.timefold.solver.core.impl.solver.termination.BasicPlumbingTermination;
 import ai.timefold.solver.core.testdomain.TestdataSolution;
 
 import org.junit.jupiter.api.Test;
@@ -41,6 +46,26 @@ void filterCacheTypeJustInTime() {
         filter(SelectionCacheType.JUST_IN_TIME, 5);
     }
 
+    @Test
+    void bailOutByTermination() {
+        var phaseScope = mock(AbstractPhaseScope.class);
+        var moveSelector = mock(MoveSelector.class);
+        var termination = mock(BasicPlumbingTermination.class);
+        var iterator = mock(Iterator.class);
+        // We set the maximum value to force it to run many evaluations
+        when(moveSelector.getSize()).thenReturn(Long.MAX_VALUE / 11);
+        when(moveSelector.isNeverEnding()).thenReturn(true);
+        when(moveSelector.iterator()).thenReturn(iterator);
+        when(iterator.hasNext()).thenReturn(true);
+        when(phaseScope.getTermination()).thenReturn(termination);
+        when(termination.isPhaseTerminated(any(AbstractPhaseScope.class))).thenReturn(false, false, true);
+        var filteredMoveSelector = FilteringMoveSelector.of(moveSelector, (scoreDirector, selection) -> false);
+        filteredMoveSelector.phaseStarted(phaseScope);
+        assertThat(filteredMoveSelector.iterator().hasNext()).isFalse();
+        // The termination returns true at the third call
+        verify(iterator, times(2)).next();
+    }
+
     public void filter(SelectionCacheType cacheType, int timesCalled) {
         MoveSelector childMoveSelector = SelectorTestUtils.mockMoveSelector(
                 new DummyMove("a1"), new DummyMove("a2"), new DummyMove("a3"), new DummyMove("a4"));