Skip to content
Tutorials Center
My learning

Topics

Java Reference ยท Concurrency

The ScheduledExecutorService interface

Reference for ScheduledExecutorService: schedule one-off tasks, repeat at a fixed rate or fixed delay, cancel scheduled tasks, and avoid silent failures.

A ScheduledExecutorService is an executor that can run tasks after a delay or repeatedly. It replaces java.util.Timer, which has only one thread and dies when a task throws. Scheduled executors can use several threads and isolate failures to the task that caused them.

You get one from Executors.newScheduledThreadPool(n) or newSingleThreadScheduledExecutor(). Each scheduling method returns a ScheduledFuture, which you use to cancel the task or read its result.

Java
ScheduledExecutorService timer = Executors.newScheduledThreadPool(1);
timer.schedule(() -> System.out.println("later"), 1, TimeUnit.SECONDS);
timer.scheduleAtFixedRate(task, 0, 5, TimeUnit.SECONDS);

Try it

Java One-off delays and ordering

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Java Repeating tasks and failures

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Syntax

Java
public interface ScheduledExecutorService extends ExecutorService
Method Description
ScheduledFuture<?> schedule(Runnable, long delay, TimeUnit) Runs once after the delay.
ScheduledFuture<V> schedule(Callable<V>, long delay, TimeUnit) Runs once and produces a result.
scheduleAtFixedRate(Runnable, long initialDelay, long period, TimeUnit) Starts runs at initialDelay, initialDelay + period, + 2 * period, and so on.
scheduleWithFixedDelay(Runnable, long initialDelay, long delay, TimeUnit) Waits delay after each run finishes before the next starts.

Throws: RejectedExecutionException if the service is shut down; IllegalArgumentException if period or delay is not positive; NullPointerException for a null task.

Usage notes

  • Fixed rate vs fixed delay. Fixed rate keeps a steady schedule and, if a run is late, the next ones follow immediately to catch up (they never overlap). Fixed delay guarantees a gap between runs, which suits polling.
  • A thrown exception stops the series. After an uncaught exception no further runs happen, and nothing is logged unless you call get(). Wrap the body in try/catch and log inside it.
  • Cancel with the returned future. cancel(false) stops future runs; cancel(true) also interrupts a run in progress.
  • shutdown() and periodic tasks. By default, shutdown() cancels periodic tasks but still runs delayed one-shot tasks already scheduled. ScheduledThreadPoolExecutor has setters to change both behaviors.
  • Runs of one periodic task never overlap, even with a bigger pool; a slow task simply delays itself.
  • Delays are minimums, not guarantees. A busy pool or a long-running earlier task delays execution.
  • It uses the monotonic clock, so changing the wall-clock time does not shift schedules. For "every day at 03:00" you need to compute the delay yourself or use a scheduler library.
  • Use a pool of at least 1. Core size 0 is allowed but is a poor fit for this class.