Package io.fluxcapacitor.common

Interface TaskScheduler

All Known Implementing Classes:
InMemoryTaskScheduler
public interface TaskScheduler
Interface for in-memory scheduling of tasks in a way that supports deterministic testing and virtualized time.

TaskScheduler enables deferred execution of tasks based on a deadline or delay. It is used by Flux Capacitor internally, but can also be applied directly for scheduling logic within applications.

Unlike typical thread-based scheduling (e.g. ScheduledExecutorService), this abstraction allows fine-grained control over when tasks are executed, making it ideal for use in test fixtures and simulations where real-time waiting would be undesirable.

  • Method Details

    • submit

      default void submit(ThrowingRunnable task)
      Immediately schedules a task for execution.
      Parameters:
      task - the task to execute

    • schedule

      default Registration schedule(Duration duration, ThrowingRunnable task)
      Schedules a task to be executed after a specified delay.
      Parameters:
      duration - the delay duration after which the task should be executed
      task - the task to execute
      Returns:
      a Registration that can be used to cancel the task before execution

    • schedule

      default Registration schedule(Instant deadline, ThrowingRunnable task)
      Schedules a task to be executed at a specific timestamp.
      Parameters:
      deadline - the Instant timestamp indicating when to execute the task
      task - the task to execute
      Returns:
      a Registration that can be used to cancel the task before execution

    • schedule

      Registration schedule(long deadline, ThrowingRunnable task)
      Schedules a task to be executed at the given epoch millisecond timestamp.
      Parameters:
      deadline - epoch milliseconds (UTC) representing the execution time
      task - the task to execute
      Returns:
      a Registration to cancel the task if needed

    • orTimeout

      default <R> CompletableFuture<R> orTimeout(CompletableFuture<R> future, Duration timeout)
      Sets a timeout for a CompletableFuture. If the future does not complete before the timeout expires, it is completed exceptionally with a TimeoutException.

      The returned future will still complete normally if the underlying task completes first.

      Type Parameters:
      R - the type of the result
      Parameters:
      future - the future to observe
      timeout - the maximum duration to wait before timing out
      Returns:
      the same future instance

    • clock

      Clock clock()
      Returns the clock associated with this scheduler. This clock is used to determine the current time for scheduling.

      In test scenarios, the clock may be a mock or virtualized instance to support deterministic test behavior.

      Returns:
      the Clock used by this scheduler

    • executeExpiredTasks

      void executeExpiredTasks()
      Executes any scheduled tasks that are due according to the scheduler's current time.

      Useful for test scenarios or manual triggering of scheduled behavior.

    • shutdown

      void shutdown()
      Shuts down the scheduler and stops execution of any pending or future tasks.

      In production use, this ensures proper resource cleanup. In test environments, this may reset scheduler state.