Package ai.timefold.solver.core.api.solver

Interface SolverManager<Solution_,ProblemId_>

Type Parameters:

Solution_ - the solution type, the class with the PlanningSolution annotation

ProblemId_ - the ID type of a submitted problem, such as Long or UUID.

All Superinterfaces:

AutoCloseable

All Known Implementing Classes:

DefaultSolverManager

public interface SolverManager<Solution_,ProblemId_>
extends AutoCloseable

A SolverManager solves multiple planning problems of the same domain, asynchronously without blocking the calling thread.

To create a SolverManager, use create(SolverFactory, SolverManagerConfig). To solve a planning problem, call solve(Object, Object, Consumer) or solveAndListen(Object, Object, Consumer).

These methods are thread-safe unless explicitly stated otherwise.

Internally a SolverManager manages a thread pool of solver threads (which call Solver.solve(Object)) and consumer threads (to handle the BestSolutionChangedEvents).

To learn more about problem change semantics, please refer to the ProblemChange Javadoc.

Method Summary

Modifier and Type	Method	Description
default @NonNull CompletableFuture<Void>	addProblemChange(@NonNull ProblemId_ problemId, @NonNull ProblemChange<Solution_> problemChange)	As defined by addProblemChanges(Object, List), only with a single ProblemChange.
@NonNull CompletableFuture<Void>	addProblemChanges(@NonNull ProblemId_ problemId, @NonNull List<ProblemChange<Solution_>> problemChangeList)	Schedules a batch of problem changes to be processed by the underlying Solver and returns immediately.
void	close()	Terminates all solvers, cancels all solver jobs that haven't (re)started yet and discards all queued ProblemChanges.
static <Solution_, ProblemId_> @NonNull SolverManager<Solution_,ProblemId_>	create(@NonNull SolverFactory<Solution_> solverFactory)	Use a SolverFactory to build a SolverManager.
static <Solution_, ProblemId_> @NonNull SolverManager<Solution_,ProblemId_>	create(@NonNull SolverFactory<Solution_> solverFactory, @NonNull SolverManagerConfig solverManagerConfig)	Use a SolverFactory and a SolverManagerConfig to build a SolverManager.
static <Solution_, ProblemId_> @NonNull SolverManager<Solution_,ProblemId_>	create(@NonNull SolverConfig solverConfig)	Use a SolverConfig to build a SolverManager.
static <Solution_, ProblemId_> @NonNull SolverManager<Solution_,ProblemId_>	create(@NonNull SolverConfig solverConfig, @NonNull SolverManagerConfig solverManagerConfig)	Use a SolverConfig and a SolverManagerConfig to build a SolverManager.
@NonNull SolverStatus	getSolverStatus(@NonNull ProblemId_ problemId)	Returns if the Solver is scheduled to solve, actively solving or not.
default @NonNull SolverJob<Solution_,ProblemId_>	solve(@NonNull ProblemId_ problemId, @NonNull Function<? super ProblemId_,? extends Solution_> problemFinder, @Nullable Consumer<? super Solution_> finalBestSolutionConsumer)	Deprecated, for removal: This API element is subject to removal in a future version. It is recommended to use solveBuilder()
default @NonNull SolverJob<Solution_,ProblemId_>	solve(@NonNull ProblemId_ problemId, @NonNull Function<? super ProblemId_,? extends Solution_> problemFinder, @Nullable Consumer<? super Solution_> finalBestSolutionConsumer, @Nullable BiConsumer<? super ProblemId_,? super Throwable> exceptionHandler)	Deprecated, for removal: This API element is subject to removal in a future version. It is recommended to use solveBuilder()
default @NonNull SolverJob<Solution_,ProblemId_>	solve(@NonNull ProblemId_ problemId, @NonNull Solution_ problem)	Submits a planning problem to solve and returns immediately.
default @NonNull SolverJob<Solution_,ProblemId_>	solve(@NonNull ProblemId_ problemId, @NonNull Solution_ problem, @Nullable Consumer<? super Solution_> finalBestSolutionConsumer)	As defined by solve(Object, Object).
default @NonNull SolverJob<Solution_,ProblemId_>	solve(@NonNull ProblemId_ problemId, @NonNull Solution_ problem, @Nullable Consumer<? super Solution_> finalBestSolutionConsumer, @Nullable BiConsumer<? super ProblemId_,? super Throwable> exceptionHandler)	Deprecated, for removal: This API element is subject to removal in a future version. It is recommended to use solveBuilder()
default @NonNull SolverJob<Solution_,ProblemId_>	solveAndListen(@NonNull ProblemId_ problemId, @NonNull Function<? super ProblemId_,? extends Solution_> problemFinder, @NonNull Consumer<? super Solution_> bestSolutionConsumer)	Deprecated, for removal: This API element is subject to removal in a future version. It is recommended to use solveBuilder() while also providing a consumer for the best solution
default @NonNull SolverJob<Solution_,ProblemId_>	solveAndListen(@NonNull ProblemId_ problemId, @NonNull Function<? super ProblemId_,? extends Solution_> problemFinder, @NonNull Consumer<? super Solution_> bestSolutionConsumer, @Nullable BiConsumer<? super ProblemId_,? super Throwable> exceptionHandler)	Deprecated, for removal: This API element is subject to removal in a future version. It is recommended to use solveBuilder() while also providing a consumer for the best solution
default @NonNull SolverJob<Solution_,ProblemId_>	solveAndListen(@NonNull ProblemId_ problemId, @NonNull Function<? super ProblemId_,? extends Solution_> problemFinder, @NonNull Consumer<? super Solution_> bestSolutionConsumer, @Nullable Consumer<? super Solution_> finalBestSolutionConsumer, @Nullable BiConsumer<? super ProblemId_,? super Throwable> exceptionHandler)	Deprecated, for removal: This API element is subject to removal in a future version. It is recommended to use solveBuilder() while also providing a consumer for the best solution
default @NonNull SolverJob<Solution_,ProblemId_>	solveAndListen(@NonNull ProblemId_ problemId, @NonNull Solution_ problem, @NonNull Consumer<? super Solution_> bestSolutionConsumer)	Submits a planning problem to solve and returns immediately.
@NonNull SolverJobBuilder<Solution_,ProblemId_>	solveBuilder()	Creates a Builder that allows to customize and submit a planning problem to solve.
void	terminateEarly(@NonNull ProblemId_ problemId)	Terminates the solver or cancels the solver job if it hasn't (re)started yet.

Method Details

create

static <Solution_,
ProblemId_>
@NonNull SolverManager<Solution_,ProblemId_> create(@NonNull SolverConfig solverConfig)

Use a SolverConfig to build a SolverManager.

When using SolutionManager too, use create(SolverFactory) instead so they reuse the same SolverFactory instance.

Type Parameters:

Solution_ - the solution type, the class with the PlanningSolution annotation

ProblemId_ - the ID type of a submitted problem, such as Long or UUID

create

static <Solution_,
ProblemId_>
@NonNull SolverManager<Solution_,ProblemId_> create(@NonNull SolverConfig solverConfig,
 @NonNull SolverManagerConfig solverManagerConfig)

Use a SolverConfig and a SolverManagerConfig to build a SolverManager.

When using SolutionManager too, use create(SolverFactory, SolverManagerConfig) instead so they reuse the same SolverFactory instance.

Type Parameters:

Solution_ - the solution type, the class with the PlanningSolution annotation

ProblemId_ - the ID type of a submitted problem, such as Long or UUID.

create

static <Solution_,
ProblemId_>
@NonNull SolverManager<Solution_,ProblemId_> create(@NonNull SolverFactory<Solution_> solverFactory)

Use a SolverFactory to build a SolverManager.

Type Parameters:

Solution_ - the solution type, the class with the PlanningSolution annotation

ProblemId_ - the ID type of a submitted problem, such as Long or UUID

create

static <Solution_,
ProblemId_>
@NonNull SolverManager<Solution_,ProblemId_> create(@NonNull SolverFactory<Solution_> solverFactory,
 @NonNull SolverManagerConfig solverManagerConfig)

Use a SolverFactory and a SolverManagerConfig to build a SolverManager.

Type Parameters:

Solution_ - the solution type, the class with the PlanningSolution annotation

ProblemId_ - the ID type of a submitted problem, such as Long or UUID.

solveBuilder

@NonNull SolverJobBuilder<Solution_,ProblemId_> solveBuilder()

Creates a Builder that allows to customize and submit a planning problem to solve.

solve

default @NonNull SolverJob<Solution_,ProblemId_> solve(@NonNull ProblemId_ problemId,
 @NonNull Solution_ problem)

Submits a planning problem to solve and returns immediately. The planning problem is solved on a solver Thread, as soon as one is available. To retrieve the final best solution, use SolverJob.getFinalBestSolution().

In server applications, it's recommended to use solve(Object, Object, Consumer) instead, to avoid loading the problem going stale if solving can't start immediately. To listen to intermediate best solutions too, use solveAndListen(Object, Object, Consumer) instead.

Defaults to logging exceptions as an error.

To stop a solver job before it naturally terminates, call SolverJob.terminateEarly().

Parameters:

problemId - a ID for each planning problem. This must be unique. Use this problemId to terminate the solver early,

problem - a PlanningSolution usually with uninitialized planning variables

solve

default @NonNull SolverJob<Solution_,ProblemId_> solve(@NonNull ProblemId_ problemId,
 @NonNull Solution_ problem,
 @Nullable Consumer<? super Solution_> finalBestSolutionConsumer)

As defined by solve(Object, Object).

Parameters:

problemId - a ID for each planning problem. This must be unique. Use this problemId to terminate the solver early, to get the status or if the problem changes while solving.

problem - a PlanningSolution usually with uninitialized planning variables

finalBestSolutionConsumer - called only once, at the end, on a consumer thread

solve

@Deprecated(forRemoval=true,
            since="1.6.0")
default @NonNull SolverJob<Solution_,ProblemId_> solve(@NonNull ProblemId_ problemId,
 @NonNull Solution_ problem,
 @Nullable Consumer<? super Solution_> finalBestSolutionConsumer,
 @Nullable BiConsumer<? super ProblemId_,? super Throwable> exceptionHandler)

Deprecated, for removal: This API element is subject to removal in a future version.

It is recommended to use solveBuilder()

As defined by solve(Object, Object).

Parameters:

problemId - a ID for each planning problem. This must be unique. Use this problemId to terminate the solver early, to get the status or if the problem changes while solving.

problem - a PlanningSolution usually with uninitialized planning variables

finalBestSolutionConsumer - called only once, at the end, on a consumer thread

exceptionHandler - called if an exception or error occurs. If null it defaults to logging the exception as an error.

solve

@Deprecated(forRemoval=true,
            since="1.6.0")
default @NonNull SolverJob<Solution_,ProblemId_> solve(@NonNull ProblemId_ problemId,
 @NonNull Function<? super ProblemId_,? extends Solution_> problemFinder,
 @Nullable Consumer<? super Solution_> finalBestSolutionConsumer)

Deprecated, for removal: This API element is subject to removal in a future version.

It is recommended to use solveBuilder()

Submits a planning problem to solve and returns immediately. The planning problem is solved on a solver Thread, as soon as one is available.

When the solver terminates, the finalBestSolutionConsumer is called once with the final best solution, on a consumer Thread, as soon as one is available. To listen to intermediate best solutions too, use solveAndListen(Object, Object, Consumer) instead.

Defaults to logging exceptions as an error.

To stop a solver job before it naturally terminates, call terminateEarly(Object).

Parameters:

problemId - an ID for each planning problem. This must be unique. Use this problemId to terminate the solver early, to get the status or if the problem changes while solving.

problemFinder - a function that returns a PlanningSolution, usually with uninitialized planning variables

finalBestSolutionConsumer - called only once, at the end, on a consumer thread

solve

@Deprecated(forRemoval=true,
            since="1.6.0")
default @NonNull SolverJob<Solution_,ProblemId_> solve(@NonNull ProblemId_ problemId,
 @NonNull Function<? super ProblemId_,? extends Solution_> problemFinder,
 @Nullable Consumer<? super Solution_> finalBestSolutionConsumer,
 @Nullable BiConsumer<? super ProblemId_,? super Throwable> exceptionHandler)

Deprecated, for removal: This API element is subject to removal in a future version.

It is recommended to use solveBuilder()

As defined by solve(Object, Function, Consumer).

Parameters:

problemId - a ID for each planning problem. This must be unique. Use this problemId to terminate the solver early, to get the status or if the problem changes while solving.

problemFinder - function that returns a PlanningSolution, usually with uninitialized planning variables

finalBestSolutionConsumer - called only once, at the end, on a consumer thread

exceptionHandler - called if an exception or error occurs. If null it defaults to logging the exception as an error.

solveAndListen

@Deprecated(forRemoval=true,
            since="1.6.0")
default @NonNull SolverJob<Solution_,ProblemId_> solveAndListen(@NonNull ProblemId_ problemId,
 @NonNull Function<? super ProblemId_,? extends Solution_> problemFinder,
 @NonNull Consumer<? super Solution_> bestSolutionConsumer)

Deprecated, for removal: This API element is subject to removal in a future version.

It is recommended to use solveBuilder() while also providing a consumer for the best solution

Submits a planning problem to solve and returns immediately. The planning problem is solved on a solver Thread, as soon as one is available.

When the solver finds a new best solution, the bestSolutionConsumer is called every time, on a consumer Thread, as soon as one is available (taking into account any throttling waiting time), unless a newer best solution is already available by then (in which case skip ahead discards it).

Defaults to logging exceptions as an error.

To stop a solver job before it naturally terminates, call terminateEarly(Object).

Parameters:

problemId - a ID for each planning problem. This must be unique. Use this problemId to terminate the solver early, to get the status or if the problem changes while solving.

problemFinder - a function that returns a PlanningSolution, usually with uninitialized planning variables

bestSolutionConsumer - called multiple times, on a consumer thread

solveAndListen

default @NonNull SolverJob<Solution_,ProblemId_> solveAndListen(@NonNull ProblemId_ problemId,
 @NonNull Solution_ problem,
 @NonNull Consumer<? super Solution_> bestSolutionConsumer)

Submits a planning problem to solve and returns immediately. The planning problem is solved on a solver Thread, as soon as one is available.

When the solver finds a new best solution, the bestSolutionConsumer is called every time, on a consumer Thread, as soon as one is available (taking into account any throttling waiting time), unless a newer best solution is already available by then (in which case skip ahead discards it).

Defaults to logging exceptions as an error.

To stop a solver job before it naturally terminates, call terminateEarly(Object).

Parameters:

problemId - a ID for each planning problem. This must be unique. Use this problemId to terminate the solver early, to get the status or if the problem changes while solving.

problem - a PlanningSolution usually with uninitialized planning variables

bestSolutionConsumer - called multiple times, on a consumer thread

solveAndListen

@Deprecated(forRemoval=true,
            since="1.6.0")
default @NonNull SolverJob<Solution_,ProblemId_> solveAndListen(@NonNull ProblemId_ problemId,
 @NonNull Function<? super ProblemId_,? extends Solution_> problemFinder,
 @NonNull Consumer<? super Solution_> bestSolutionConsumer,
 @Nullable BiConsumer<? super ProblemId_,? super Throwable> exceptionHandler)

Deprecated, for removal: This API element is subject to removal in a future version.

It is recommended to use solveBuilder() while also providing a consumer for the best solution

As defined by solveAndListen(Object, Function, Consumer).

Parameters:

problemId - an ID for each planning problem. This must be unique. Use this problemId to terminate the solver early, to get the status or if the problem changes while solving.

problemFinder - function that returns a PlanningSolution, usually with uninitialized planning variables

bestSolutionConsumer - called multiple times, on a consumer thread

exceptionHandler - called if an exception or error occurs. If null it defaults to logging the exception as an error.

solveAndListen

@Deprecated(forRemoval=true,
            since="1.6.0")
default @NonNull SolverJob<Solution_,ProblemId_> solveAndListen(@NonNull ProblemId_ problemId,
 @NonNull Function<? super ProblemId_,? extends Solution_> problemFinder,
 @NonNull Consumer<? super Solution_> bestSolutionConsumer,
 @Nullable Consumer<? super Solution_> finalBestSolutionConsumer,
 @Nullable BiConsumer<? super ProblemId_,? super Throwable> exceptionHandler)

Deprecated, for removal: This API element is subject to removal in a future version.

It is recommended to use solveBuilder() while also providing a consumer for the best solution

As defined by solveAndListen(Object, Function, Consumer).

The final best solution is delivered twice: first to the bestSolutionConsumer when it is found and then again to the finalBestSolutionConsumer when the solver terminates. Do not store the solution twice. This allows for use cases that only process the Score first (during best solution changed events) and then store the solution upon termination.

Parameters:

problemId - an ID for each planning problem. This must be unique. Use this problemId to terminate the solver early, to get the status or if the problem changes while solving.

problemFinder - function that returns a PlanningSolution, usually with uninitialized planning variables

bestSolutionConsumer - called multiple times, on a consumer thread

finalBestSolutionConsumer - called only once, at the end, on a consumer thread. That final best solution is already consumed by the bestSolutionConsumer earlier.

exceptionHandler - called if an exception or error occurs. If null it defaults to logging the exception as an error.

getSolverStatus

@NonNull SolverStatus getSolverStatus(@NonNull ProblemId_ problemId)

Returns if the Solver is scheduled to solve, actively solving or not.

Returns SolverStatus.NOT_SOLVING if the solver already terminated or if the problemId was never added. To distinguish between both cases, use SolverJob.getSolverStatus() instead. Here, that distinction is not supported because it would cause a memory leak.

Parameters:

problemId - a value given to solve(Object, Object, Consumer) or solveAndListen(Object, Object, Consumer)

addProblemChange

default @NonNull CompletableFuture<Void> addProblemChange(@NonNull ProblemId_ problemId,
 @NonNull ProblemChange<Solution_> problemChange)

As defined by addProblemChanges(Object, List), only with a single ProblemChange. Prefer to submit multiple ProblemChanges at once to reduce the considerable overhead of multiple calls.

addProblemChanges

@NonNull CompletableFuture<Void> addProblemChanges(@NonNull ProblemId_ problemId,
 @NonNull List<ProblemChange<Solution_>> problemChangeList)

Schedules a batch of problem changes to be processed by the underlying Solver and returns immediately. If the solver already terminated or the problemId was never added, throws an exception. The same applies if the underlying Solver is not in the SolverStatus.SOLVING_ACTIVE state.

Parameters:

problemId - a value given to solve(Object, Object, Consumer) or solveAndListen(Object, Object, Consumer)

problemChangeList - a list of ProblemChanges to apply to the problem

Returns:

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 Also:

• Learn more about problem change semantics.

terminateEarly

void terminateEarly(@NonNull ProblemId_ problemId)

Terminates the solver or cancels the solver job if it hasn't (re)started yet.

Does nothing if the solver already terminated or the problemId was never added. To distinguish between both cases, use SolverJob.terminateEarly() instead. Here, that distinction is not supported because it would cause a memory leak.

Waits for the termination or cancellation to complete before returning. During termination, a bestSolutionConsumer could still be called. When the solver terminates, the finalBestSolutionConsumer is executed with the latest best solution. These consumers run on a consumer thread independently of the termination and may still run even after this method returns.

Parameters:

problemId - a value given to solve(Object, Object, Consumer) or solveAndListen(Object, Object, Consumer)

close

void close()

Terminates all solvers, cancels all solver jobs that haven't (re)started yet and discards all queued ProblemChanges. Releases all thread pool resources.

No new planning problems can be submitted after calling this method.

Specified by:

close in interface AutoCloseable