Cancellation and timeouts

suggest change

Sooner or later every concurrent program has to stop work that is no longer needed: the user pressed "cancel", a request took too long, or one of several parallel tasks failed and the rest are pointless.

Java has no way to forcibly kill a thread. Thread.stop() was deprecated in Java 1.2 because it could leave objects in a corrupt state, and since Java 20 it just throws UnsupportedOperationException. Cancellation in Java is cooperative: you ask a thread to stop, and the code running on it checks for that request and exits cleanly.

The standard request is thread interruption. Almost every cancellation and timeout mechanism in the JDK is built on it:

This article shows how to use them together. For the low-level details of the interrupt flag see Thread Interruption Stopping Threads and Handling InterruptedException.

Interrupting a thread

thread.interrupt() does two things:

A thread that spends most of its time blocked reacts to InterruptedException:

public class InterruptSleeping {
    public static void main(String[] args) throws InterruptedException {
        Thread worker = new Thread(() -> {
            int i = 0;
            try {
                while (true) {
                    System.out.println("working " + i++);
                    Thread.sleep(100);
                }
            } catch (InterruptedException e) {
                System.out.println("interrupted, cleaning up");
            }
        });

        worker.start();
        Thread.sleep(250);
        worker.interrupt();   // ask the worker to stop
        worker.join();        // wait until it actually stopped
        System.out.println("worker state: " + worker.getState());
    }
}
working 0
working 1
working 2
interrupted, cleaning up
worker state: TERMINATED

Note join() after interrupt(). Interrupting only requests cancellation; the thread may need time to finish its cleanup.

A thread doing pure computation never blocks, so it never sees InterruptedException. It has to poll the flag:

Thread cruncher = new Thread(() -> {
    long iterations = 0;
    while (!Thread.currentThread().isInterrupted()) {
        iterations++;            // some CPU-bound work
    }
    System.out.println("stopped, flag still set: "
            + Thread.currentThread().isInterrupted());
});

cruncher.start();
Thread.sleep(100);
cruncher.interrupt();
cruncher.join();
stopped, flag still set: true

There are two ways to read the flag and they differ in an important way:

Method Clears the flag?
Thread.currentThread().isInterrupted() no
Thread.interrupted() (static) yes

Use isInterrupted() to check, and use Thread.interrupted() only when you are about to handle the interruption, typically by throwing InterruptedException:

static void processAll(List<String> items) throws InterruptedException {
    for (String item : items) {
        if (Thread.interrupted()) {
            throw new InterruptedException("cancelled while processing");
        }
        process(item);
    }
}

In a long CPU loop, checking the flag every iteration is cheap, but you can also check every few thousand iterations.

Don't swallow InterruptedException

When a blocking call throws InterruptedException, the flag has already been cleared. If you catch the exception and carry on, the cancellation request is lost and the caller's loop keeps running forever.

You have two correct options. The best one is to let it propagate by declaring throws InterruptedException. When you can't, because you are inside a Runnable or a method with a fixed signature, restore the flag so code further up the stack can still see it:

// Wrong: the interrupt is lost
try {
    Thread.sleep(1000);
} catch (InterruptedException e) {
    e.printStackTrace();
}

// Right: restore the flag and stop what you are doing
try {
    Thread.sleep(1000);
} catch (InterruptedException e) {
    Thread.currentThread().interrupt();
    return;
}

More on this in Pitfall - Catching InterruptedException.

Timeouts on blocking calls

Most blocking methods in java.util.concurrent have a variant that takes a timeout. Instead of throwing on timeout, most of them return a value you have to check:

Blocking call With timeout On timeout
thread.join() thread.join(Duration) (Java 19+) returns false
queue.take() queue.poll(timeout, unit) returns null
queue.put(e) queue.offer(e, timeout, unit) returns false
lock.lock() lock.tryLock(timeout, unit) returns false
latch.await() latch.await(timeout, unit) returns false
semaphore.acquire() semaphore.tryAcquire(timeout, unit) returns false
condition.await() condition.await(timeout, unit) returns false
future.get() future.get(timeout, unit) throws TimeoutException
executor.awaitTermination(...) (always has a timeout) returns false

All of them also throw InterruptedException, so a timed wait can be both timed out and cancelled.

import java.util.concurrent.ArrayBlockingQueue;
import java.util.concurrent.BlockingQueue;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.locks.ReentrantLock;

public class TimedWaits {
    public static void main(String[] args) throws InterruptedException {
        BlockingQueue<String> queue = new ArrayBlockingQueue<>(10);
        String msg = queue.poll(200, TimeUnit.MILLISECONDS);
        System.out.println("poll returned: " + msg);

        ReentrantLock lock = new ReentrantLock();
        Thread holder = new Thread(() -> {
            lock.lock();
            try {
                Thread.sleep(1000);
            } catch (InterruptedException ignored) {
                Thread.currentThread().interrupt();
            } finally {
                lock.unlock();
            }
        });
        holder.start();
        Thread.sleep(50);   // let the other thread grab the lock

        if (lock.tryLock(200, TimeUnit.MILLISECONDS)) {
            try {
                System.out.println("got the lock");
            } finally {
                lock.unlock();
            }
        } else {
            System.out.println("could not get the lock in 200 ms");
        }
        holder.interrupt();
        holder.join();
    }
}
poll returned: null
could not get the lock in 200 ms

Two blocking operations can't be interrupted at all: entering a synchronized block and calling lock.lock(). If you need a lock wait that can be cancelled or timed out, use ReentrantLock with lockInterruptibly() or tryLock(timeout, unit).

Future: get with timeout, then cancel

A Future returned by ExecutorService.submit is the usual handle for cancelling a task. get(timeout, unit) waits for at most that long and throws TimeoutException. The task keeps running after the timeout, so you normally follow up with cancel(true), which interrupts the thread running it:

import java.util.concurrent.*;

public class FutureTimeout {
    public static void main(String[] args) throws Exception {
        ExecutorService pool = Executors.newFixedThreadPool(2);

        Future<String> future = pool.submit(() -> {
            try {
                Thread.sleep(5_000);   // simulates a slow call
                return "result";
            } catch (InterruptedException e) {
                System.out.println("task: interrupted, giving up");
                throw e;
            }
        });

        try {
            String result = future.get(300, TimeUnit.MILLISECONDS);
            System.out.println("got " + result);
        } catch (TimeoutException e) {
            System.out.println("main: timed out, cancelling");
            future.cancel(true);
        }

        pool.shutdown();
        pool.awaitTermination(1, TimeUnit.SECONDS);

        System.out.println("state: " + future.state());
        System.out.println("isCancelled: " + future.isCancelled());
        System.out.println("isDone: " + future.isDone());
        try {
            future.get();
        } catch (CancellationException e) {
            System.out.println("get() threw CancellationException");
        }
    }
}
main: timed out, cancelling
task: interrupted, giving up
state: CANCELLED
isCancelled: true
isDone: true
get() threw CancellationException

Things to know about cancel:

cancel(true) is only as good as the task's response to interruption. A task that swallows InterruptedException or loops without checking the flag keeps running and keeps occupying a pool thread.

If you don't want to block while waiting, schedule the cancellation instead:

ScheduledExecutorService timer = Executors.newSingleThreadScheduledExecutor();
Future<?> task = pool.submit(this::longRunningJob);
timer.schedule(() -> task.cancel(true), 2, TimeUnit.SECONDS);

Cancelling a future that already finished is harmless, so the scheduled cancel doesn't need to check.

Timeouts for groups of tasks

invokeAll(tasks, timeout, unit) runs all tasks and waits until they all finish or the timeout expires. Tasks that haven't finished by then are cancelled with interruption:

import java.util.List;
import java.util.concurrent.*;

public class InvokeAllTimeout {
    public static void main(String[] args) throws InterruptedException {
        List<Callable<String>> tasks = List.of(
                () -> { Thread.sleep(100); return "fast"; },
                () -> { Thread.sleep(200); return "medium"; },
                () -> { Thread.sleep(5_000); return "slow"; });

        try (ExecutorService pool = Executors.newFixedThreadPool(3)) {
            List<Future<String>> futures = pool.invokeAll(tasks, 1, TimeUnit.SECONDS);
            for (Future<String> f : futures) {
                switch (f.state()) {
                    case SUCCESS -> System.out.println("ok: " + f.resultNow());
                    case FAILED -> System.out.println("failed: " + f.exceptionNow());
                    case CANCELLED -> System.out.println("cancelled");
                    case RUNNING -> System.out.println("still running?");
                }
            }
        }
    }
}
ok: fast
ok: medium
cancelled

The returned list is in the same order as the tasks, and every future in it is done.

invokeAny(tasks, timeout, unit) returns the result of the first task that completes successfully and cancels the rest. If none succeeds in time it throws TimeoutException. This is handy for querying several replicas and taking the fastest answer.

Since Java 19 ExecutorService is AutoCloseable. close() calls shutdown() and waits for tasks to finish; if the waiting thread is interrupted, it calls shutdownNow(). To stop a pool with a time limit yourself, use the pattern from the ExecutorService javadoc:

static void shutdownAndAwait(ExecutorService pool, Duration timeout) {
    pool.shutdown();                       // no new tasks
    try {
        if (!pool.awaitTermination(timeout.toMillis(), TimeUnit.MILLISECONDS)) {
            List<Runnable> neverStarted = pool.shutdownNow();  // interrupt running tasks
            System.out.println(neverStarted.size() + " tasks never started");
            if (!pool.awaitTermination(timeout.toMillis(), TimeUnit.MILLISECONDS)) {
                System.err.println("pool did not terminate");
            }
        }
    } catch (InterruptedException e) {
        pool.shutdownNow();
        Thread.currentThread().interrupt();
    }
}

See also Wait for completion of all tasks in ExecutorService and Signals and graceful shutdown.

CompletableFuture timeouts

CompletableFuture (Java 9+) has two timeout methods:

Both modify the future they are called on and return it, so they fit in a chain. There is a big catch: neither one stops the work. CompletableFuture isn't bound to the thread that computes it, so timing out (or calling cancel(true), which ignores its argument) only completes the future. The supplier keeps running in the background:

import java.util.concurrent.*;

public class CompletableTimeouts {
    static String slowCall(String name, long millis) {
        try {
            Thread.sleep(millis);
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
            throw new CompletionException(e);
        }
        System.out.println(name + " finished anyway");
        return name;
    }

    public static void main(String[] args) throws InterruptedException {
        CompletableFuture<String> a = CompletableFuture
                .supplyAsync(() -> slowCall("a", 500))
                .completeOnTimeout("fallback", 100, TimeUnit.MILLISECONDS);
        System.out.println("a: " + a.join());

        CompletableFuture<String> b = CompletableFuture
                .supplyAsync(() -> slowCall("b", 500))
                .orTimeout(100, TimeUnit.MILLISECONDS);
        try {
            b.join();
        } catch (CompletionException e) {
            System.out.println("b: " + e.getCause());
        }

        Thread.sleep(1_000);   // keep the JVM alive to show the tasks still run
    }
}
a: fallback
b: java.util.concurrent.TimeoutException
a finished anyway
b finished anyway

join() wraps the failure in CompletionException; get() would wrap it in ExecutionException. Either way the cause is the TimeoutException.

For a timeout that also frees resources, the work itself must be cancellable. Run it with ExecutorService.submit and use Future.cancel(true), give the underlying call its own timeout (HTTP, JDBC and socket APIs all have one), or pass a cancellation flag the task checks. More on chaining in CompletableFuture.

A deadline across several steps

A per-call timeout isn't enough when an operation makes several blocking calls. Five calls with a one-second timeout each can take five seconds. Compute a deadline once and give each call the time that's left. Use System.nanoTime(), which is monotonic, not System.currentTimeMillis(), which jumps when the wall clock is adjusted:

import java.time.Duration;
import java.util.ArrayList;
import java.util.List;
import java.util.concurrent.*;

public class DeadlineExample {
    record Deadline(long nanoTime) {
        static Deadline after(Duration d) {
            return new Deadline(System.nanoTime() + d.toNanos());
        }

        long remainingNanos() throws TimeoutException {
            long left = nanoTime - System.nanoTime();
            if (left <= 0) throw new TimeoutException("deadline exceeded");
            return left;
        }
    }

    // collect `count` messages, all of them within the deadline
    static List<String> receive(BlockingQueue<String> queue, int count, Deadline deadline)
            throws InterruptedException, TimeoutException {
        List<String> got = new ArrayList<>();
        while (got.size() < count) {
            String msg = queue.poll(deadline.remainingNanos(), TimeUnit.NANOSECONDS);
            if (msg == null) throw new TimeoutException("got only " + got);
            got.add(msg);
        }
        return got;
    }

    public static void main(String[] args) throws InterruptedException {
        BlockingQueue<String> queue = new LinkedBlockingQueue<>();
        Thread producer = Thread.ofVirtual().start(() -> {
            try {
                for (int i = 1; i <= 5; i++) {
                    Thread.sleep(150);
                    queue.put("msg" + i);
                }
            } catch (InterruptedException e) {
                Thread.currentThread().interrupt();
            }
        });

        try {
            System.out.println(receive(queue, 5, Deadline.after(Duration.ofMillis(500))));
        } catch (TimeoutException e) {
            System.out.println("timeout: " + e.getMessage());
        }
        producer.interrupt();
    }
}
timeout: got only [msg1, msg2, msg3]

Each message arrives within 150 ms, so a per-call timeout of 500 ms would never fire, yet the whole operation needs 750 ms. The deadline catches that.

Timeouts for network I/O

Classic blocking I/O on java.net.Socket and InputStream does not respond to interruption on a platform thread. A thread stuck in read() stays stuck until data arrives, the connection drops, or the socket is closed from another thread. So network code must set its own timeouts:

try (Socket socket = new Socket()) {
    socket.connect(new InetSocketAddress("example.com", 80), 2_000); // connect timeout
    socket.setSoTimeout(5_000);                                       // read timeout
    InputStream in = socket.getInputStream();
    int b = in.read();   // throws SocketTimeoutException after 5 s of silence
}

Without connect(addr, timeout), a connection attempt can hang for the operating system's TCP timeout, which can be minutes. setSoTimeout is a timeout on each read(), not on the whole response; a server that sends one byte every 4 seconds never triggers it. Use a deadline or a watchdog for a total limit. The socket remains usable after a SocketTimeoutException.

On virtual threads (Java 21+) this is better: interrupting a virtual thread blocked in a Socket, ServerSocket or DatagramSocket operation closes the socket and makes the call throw SocketException. NIO channels that implement InterruptibleChannel (such as SocketChannel and FileChannel) behave the same way on any thread, throwing ClosedByInterruptException.

java.net.http.HttpClient has both a connect timeout on the client and a total timeout per request:

import java.net.URI;
import java.net.http.*;
import java.time.Duration;

try (HttpClient client = HttpClient.newBuilder()
        .connectTimeout(Duration.ofSeconds(3))
        .build()) {
    HttpRequest request = HttpRequest.newBuilder(URI.create("https://httpbin.org/delay/10"))
            .timeout(Duration.ofSeconds(2))   // time until response headers arrive
            .build();
    HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.statusCode());
} catch (HttpTimeoutException e) {
    System.out.println("timed out: " + e.getClass().getSimpleName());
}
timed out: HttpTimeoutException

A connect timeout throws HttpConnectTimeoutException, a subclass of HttpTimeoutException. client.send also throws InterruptedException, so it can be cancelled by interrupting the calling thread, and cancelling the CompletableFuture from sendAsync with cancel(true) aborts the exchange. For JDBC, the equivalent is Statement.setQueryTimeout(seconds) and Statement.cancel().

Structured concurrency

Structured concurrency, still a preview API in Java 25 and 26 (run with --enable-preview), ties the lifetime of subtasks to a block of code. When the scope's timeout expires, or one subtask fails with a joiner that requires all to succeed, the scope interrupts the remaining subtasks and waits for them before join() returns, so nothing is left running in the background:

import java.time.Duration;
import java.util.concurrent.StructuredTaskScope;
import java.util.concurrent.StructuredTaskScope.Joiner;
import java.util.concurrent.StructuredTaskScope.Subtask;

String userAndOrders(long id) throws InterruptedException {
    try (var scope = StructuredTaskScope.open(
            Joiner.<String>awaitAllSuccessfulOrThrow(),
            cf -> cf.withTimeout(Duration.ofSeconds(2)))) {
        Subtask<String> user = scope.fork(() -> fetchUser(id));
        Subtask<String> orders = scope.fork(() -> fetchOrders(id));
        scope.join();   // throws StructuredTaskScope.TimeoutException after 2 s
        return user.get() + " " + orders.get();
    }
}

Subtasks run on virtual threads by default. As a preview, the API may still change between releases.

Writing cancellable code: a checklist

Summary

Feedback about page:

Feedback:
Optional: your email if you want me to get back to you:



Table Of Contents