feat: allow SolverManager and SolverJob to submit problem changes in batches

Author: triceo

core/src/main/java/ai/timefold/solver/core/api/solver/SolverJob.java

@@ -1,6 +1,8 @@
 package ai.timefold.solver.core.api.solver;
 
 import java.time.Duration;
+import java.util.Collections;
+import java.util.List;
 import java.util.UUID;
 import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.ExecutionException;
@@ -36,16 +38,26 @@ public interface SolverJob<Solution_, ProblemId_> {
     SolverStatus getSolverStatus();
 
     /**
-     * Schedules a {@link ProblemChange} to be processed by the underlying {@link Solver} and returns immediately.
-     * <p>
-     * To learn more about problem change semantics, please refer to the {@link ProblemChange} Javadoc.
+     * As defined by {@link #addProblemChanges(List)}, only for a single problem change.
+     * Prefer to submit multiple {@link ProblemChange}s at once to reduce the considerable overhead of multiple calls.
+     */
+    @NonNull
+    default CompletableFuture<Void> addProblemChange(@NonNull ProblemChange<Solution_> problemChange) {
+        return addProblemChanges(Collections.singletonList(problemChange));
+    }
+
+    /**
+     * Schedules a batch of {@link ProblemChange problem changes} to be processed
+     * by the underlying {@link Solver} and returns immediately.
      *
+     * @param problemChangeList at least one problem change to be processed
      * @return completes after the best solution containing this change has been consumed.
      * @throws IllegalStateException if the underlying {@link Solver} is not in the {@link SolverStatus#SOLVING_ACTIVE}
      *         state
+     * @see ProblemChange Learn more about problem change semantics.
      */
     @NonNull
-    CompletableFuture<Void> addProblemChange(@NonNull ProblemChange<Solution_> problemChange);
+    CompletableFuture<Void> addProblemChanges(@NonNull List<ProblemChange<Solution_>> problemChangeList);
 
     /**
      * Terminates the solver or cancels the solver job if it hasn't (re)started yet.

core/src/main/java/ai/timefold/solver/core/api/solver/SolverManager.java

@@ -1,5 +1,7 @@
 package ai.timefold.solver.core.api.solver;
 
+import java.util.Collections;
+import java.util.List;
 import java.util.UUID;
 import java.util.concurrent.CompletableFuture;
 import java.util.function.BiConsumer;
@@ -381,22 +383,32 @@ public interface SolverManager<Solution_, ProblemId_> extends AutoCloseable {
     @NonNull
     SolverStatus getSolverStatus(@NonNull ProblemId_ problemId);
 
-    // TODO Future features
-    //    void reloadProblem(ProblemId_ problemId, Function<? super ProblemId_, Solution_> problemFinder);
+    /**
+     * As defined by {@link #addProblemChanges(Object, List)}, only with a single {@link ProblemChange}.
+     * Prefer to submit multiple {@link ProblemChange}s at once to reduce the considerable overhead of multiple calls.
+     */
+    @NonNull
+    default CompletableFuture<Void> addProblemChange(@NonNull ProblemId_ problemId,
+            @NonNull ProblemChange<Solution_> problemChange) {
+        return addProblemChanges(problemId, Collections.singletonList(problemChange));
+    }
 
     /**
-     * Schedules a {@link ProblemChange} to be processed by the underlying {@link Solver} and returns immediately.
+     * Schedules a batch of {@link ProblemChange problem changes} to be processed
+     * by the underlying {@link Solver} and returns immediately.
      * If the solver already terminated or the problemId was never added, throws an exception.
      * The same applies if the underlying {@link Solver} is not in the {@link SolverStatus#SOLVING_ACTIVE} state.
      *
      * @param problemId a value given to {@link #solve(Object, Object, Consumer)}
      *        or {@link #solveAndListen(Object, Object, Consumer)}
+     * @param problemChangeList a list of {@link ProblemChange}s to apply to the problem
      * @return completes after the best solution containing this change has been consumed.
      * @throws IllegalStateException if there is no solver actively solving the problem associated with the problemId
      * @see ProblemChange Learn more about problem change semantics.
      */
     @NonNull
-    CompletableFuture<Void> addProblemChange(@NonNull ProblemId_ problemId, @NonNull ProblemChange<Solution_> problemChange);
+    CompletableFuture<Void> addProblemChanges(@NonNull ProblemId_ problemId,
+            @NonNull List<ProblemChange<Solution_>> problemChangeList);
 
     /**
      * Terminates the solver or cancels the solver job if it hasn't (re)started yet.

core/src/main/java/ai/timefold/solver/core/impl/solver/BestSolutionHolder.java

@@ -129,22 +129,22 @@ void set(Solution_ bestSolution, BooleanSupplier isEveryProblemChangeProcessed)
     }
 
     /**
-     * Adds a new problem change to a solver and registers the problem change
+     * Adds a batch of problem changes to a solver and registers them
      * to be later retrieved together with a relevant best solution by the {@link #take()} method.
      *
      * @return CompletableFuture that will be completed after the best solution containing this change is passed to
      *         a user-defined Consumer.
      */
     @NonNull
-    CompletableFuture<Void> addProblemChange(Solver<Solution_> solver, ProblemChange<Solution_> problemChange) {
+    CompletableFuture<Void> addProblemChange(Solver<Solution_> solver, List<ProblemChange<Solution_>> problemChangeList) {
         var futureProblemChange = new CompletableFuture<Void>();
         synchronized (this) {
             // This actually needs to be synchronized, 
             // as we want the new problem change and its version to be linked.  
             var futureProblemChangeList =
                     problemChangesPerVersionRef.get().computeIfAbsent(currentVersion.get(), version -> new ArrayList<>());
             futureProblemChangeList.add(futureProblemChange);
-            solver.addProblemChange(problemChange);
+            solver.addProblemChanges(problemChangeList);
         }
         return futureProblemChange;
     }

core/src/main/java/ai/timefold/solver/core/impl/solver/DefaultSolver.java

@@ -131,29 +131,30 @@ public boolean isTerminateEarly() {
 
     @Override
     public boolean addProblemFactChange(@NonNull ProblemFactChange<Solution_> problemFactChange) {
-        return basicPlumbingTermination.addProblemChange(ProblemChangeAdapter.create(problemFactChange));
+        return addProblemFactChanges(Collections.singletonList(problemFactChange));
     }
 
     @Override
     public boolean addProblemFactChanges(@NonNull List<ProblemFactChange<Solution_>> problemFactChangeList) {
         Objects.requireNonNull(problemFactChangeList,
                 () -> "The list of problem fact changes (" + problemFactChangeList + ") cannot be null.");
-        List<ProblemChangeAdapter<Solution_>> problemChangeAdapterList = problemFactChangeList.stream()
+        return basicPlumbingTermination.addProblemChanges(problemFactChangeList.stream()
                 .map(ProblemChangeAdapter::create)
-                .collect(Collectors.toList());
-        return basicPlumbingTermination.addProblemChanges(problemChangeAdapterList);
+                .collect(Collectors.toList()));
     }
 
     @Override
     public void addProblemChange(@NonNull ProblemChange<Solution_> problemChange) {
-        basicPlumbingTermination.addProblemChange(ProblemChangeAdapter.create(problemChange));
+        addProblemChanges(Collections.singletonList(problemChange));
     }
 
     @Override
     public void addProblemChanges(@NonNull List<ProblemChange<Solution_>> problemChangeList) {
         Objects.requireNonNull(problemChangeList,
                 () -> "The list of problem changes (" + problemChangeList + ") cannot be null.");
-        problemChangeList.forEach(this::addProblemChange);
+        basicPlumbingTermination.addProblemChanges(problemChangeList.stream()
+                .map(ProblemChangeAdapter::create)
+                .toList());
     }
 
     @Override

core/src/main/java/ai/timefold/solver/core/impl/solver/DefaultSolverJob.java

@@ -1,6 +1,7 @@
 package ai.timefold.solver.core.impl.solver;
 
 import java.time.Duration;
+import java.util.List;
 import java.util.Objects;
 import java.util.UUID;
 import java.util.concurrent.Callable;
@@ -158,14 +159,18 @@ private void solvingTerminated() {
     }
 
     @Override
-    public @NonNull CompletableFuture<Void> addProblemChange(@NonNull ProblemChange<Solution_> problemChange) {
-        Objects.requireNonNull(problemChange, () -> "A problem change (%s) must not be null.".formatted(problemId));
-        if (solverStatus == SolverStatus.NOT_SOLVING) {
-            throw new IllegalStateException("Cannot add the problem change (%s) because the solver job (%s) is not solving."
-                    .formatted(problemChange, solverStatus));
+    public @NonNull CompletableFuture<Void> addProblemChanges(@NonNull List<ProblemChange<Solution_>> problemChangeList) {
+        Objects.requireNonNull(problemChangeList, () -> "A problem change list for problem (%s) must not be null."
+                .formatted(problemId));
+        if (problemChangeList.isEmpty()) {
+            throw new IllegalArgumentException("The problem change list for problem (%s) must not be empty."
+                    .formatted(problemId));
+        } else if (solverStatus == SolverStatus.NOT_SOLVING) {
+            throw new IllegalStateException("Cannot add the problem changes (%s) because the solver job (%s) is not solving."
+                    .formatted(problemChangeList, solverStatus));
         }
 
-        return bestSolutionHolder.addProblemChange(solver, problemChange);
+        return bestSolutionHolder.addProblemChange(solver, problemChangeList);
     }
 
     @Override

core/src/main/java/ai/timefold/solver/core/impl/solver/DefaultSolverManager.java

@@ -1,5 +1,6 @@
 package ai.timefold.solver.core.impl.solver;
 
+import java.util.List;
 import java.util.Map;
 import java.util.Objects;
 import java.util.UUID;
@@ -143,16 +144,16 @@ SolverJob<Solution_, ProblemId_> solve(ProblemId_ problemId,
     //    }
 
     @Override
-    public @NonNull CompletableFuture<Void> addProblemChange(@NonNull ProblemId_ problemId,
-            @NonNull ProblemChange<Solution_> problemChange) {
+    public @NonNull CompletableFuture<Void> addProblemChanges(@NonNull ProblemId_ problemId,
+            @NonNull List<ProblemChange<Solution_>> problemChangeList) {
         DefaultSolverJob<Solution_, ProblemId_> solverJob = getSolverJob(problemId);
         if (solverJob == null) {
             // We cannot distinguish between "already terminated" and "never solved" without causing a memory leak.
             throw new IllegalStateException(
-                    "Cannot add the problem change (" + problemChange + ") because there is no solver solving the problemId ("
-                            + problemId + ").");
+                    "Cannot add the problem changes (%s) because there is no solver solving the problemId (%s)."
+                            .formatted(problemChangeList, problemId));
         }
-        return solverJob.addProblemChange(problemChange);
+        return solverJob.addProblemChanges(problemChangeList);
     }
 
     @Override

core/src/main/java/ai/timefold/solver/core/impl/solver/termination/BasicPlumbingTermination.java

@@ -81,18 +81,6 @@ public synchronized boolean waitForRestartSolverDecision() {
         }
     }
 
-    /**
-     * Concurrency note: unblocks {@link #waitForRestartSolverDecision()}.
-     *
-     * @param problemChange never null
-     * @return as specified by {@link Collection#add}
-     */
-    public synchronized boolean addProblemChange(ProblemChangeAdapter<Solution_> problemChange) {
-        boolean added = problemChangeQueue.add(problemChange);
-        notifyAll();
-        return added;
-    }
-
     /**
      * Concurrency note: unblocks {@link #waitForRestartSolverDecision()}.
      *

core/src/test/java/ai/timefold/solver/core/impl/solver/BestSolutionHolderTest.java

@@ -5,13 +5,15 @@
 import static org.mockito.Mockito.times;
 import static org.mockito.Mockito.verify;
 
+import java.util.List;
 import java.util.concurrent.CompletableFuture;
 
 import ai.timefold.solver.core.api.solver.Solver;
 import ai.timefold.solver.core.api.solver.change.ProblemChange;
 import ai.timefold.solver.core.impl.testdata.domain.TestdataSolution;
 
 import org.junit.jupiter.api.Test;
+import org.mockito.Mockito;
 
 class BestSolutionHolderTest {
 
@@ -78,8 +80,9 @@ void cancelPendingChanges_noChangesRetrieved() {
     private CompletableFuture<Void> addProblemChange(BestSolutionHolder<TestdataSolution> bestSolutionHolder) {
         Solver<TestdataSolution> solver = mock(Solver.class);
         ProblemChange<TestdataSolution> problemChange = mock(ProblemChange.class);
-        CompletableFuture<Void> futureChange = bestSolutionHolder.addProblemChange(solver, problemChange);
-        verify(solver, times(1)).addProblemChange(problemChange);
+        CompletableFuture<Void> futureChange = bestSolutionHolder.addProblemChange(solver, List.of(problemChange));
+        verify(solver, times(1)).addProblemChanges(
+                Mockito.argThat(problemChanges -> problemChanges.size() == 1 && problemChanges.get(0) == problemChange));
         return futureChange;
     }
 }

core/src/test/java/ai/timefold/solver/core/impl/solver/ConsumerSupportTest.java

@@ -132,7 +132,7 @@ void pendingProblemChangesAreCanceled_afterFinalBestSolutionIsConsumed() throws
     }
 
     private CompletableFuture<Void> addProblemChange(BestSolutionHolder<TestdataSolution> bestSolutionHolder) {
-        return bestSolutionHolder.addProblemChange(mock(Solver.class), mock(ProblemChange.class));
+        return bestSolutionHolder.addProblemChange(mock(Solver.class), List.of(mock(ProblemChange.class)));
     }
 
     private void consumeIntermediateBestSolution(TestdataSolution bestSolution) {

core/src/test/java/ai/timefold/solver/core/impl/solver/termination/BasicPlumbingTerminationTest.java

@@ -4,6 +4,7 @@
 import static org.mockito.Mockito.mock;
 
 import java.util.Arrays;
+import java.util.Collections;
 import java.util.concurrent.atomic.AtomicInteger;
 
 import ai.timefold.solver.core.impl.score.director.InnerScoreDirector;
@@ -23,7 +24,7 @@ void addProblemChangeWithoutDaemon() {
         assertThat(basicPlumbingTermination.waitForRestartSolverDecision()).isFalse();
         ProblemChangeAdapter<TestdataSolution> problemChangeAdapter =
                 ProblemChangeAdapter.create((workingSolution, problemChangeDirector) -> count.getAndIncrement());
-        basicPlumbingTermination.addProblemChange(problemChangeAdapter);
+        basicPlumbingTermination.addProblemChanges(Collections.singletonList(problemChangeAdapter));
         assertThat(basicPlumbingTermination.waitForRestartSolverDecision()).isTrue();
         assertThat(count).hasValue(0);