Cancellation And Interruption

Cancellation and interruption

Purpose

Make abandonment observable and bounded across the whole work graph. Interruption is one cooperative signal; resource close, protocol abort, cancellation tokens, deadlines and process isolation may be needed. Returning a timeout/cancelled result while work continues is a semantic and capacity state, not necessarily successful cancellation.

The authoring/API reference baseline is JDK 25; inspect the target project's compiler release/toolchain, deployed runtime, thread type and client/provider versions before selecting a mechanism. Virtual threads require JDK 21+ for final support; structured concurrency in JDK 25 is preview and requires that release's preview compilation/runtime configuration. Do not upgrade Java, enable preview or replace the client merely to apply this skill. Use structured-concurrency for the exact scope API and timeouts-and-deadlines for budget selection. If ownership or provider semantics are unknown, identify the missing evidence and propose a bounded control experiment; do not claim a stop guarantee from the API name.

Cancellation contract

work owner and terminal states:
sources: caller, deadline, sibling failure, shutdown, overload, admin
winner/precedence when sources race:
signal per execution/blocking/resource layer:
observation/check points and maximum cancellation latency:
downstream propagation and residual work:
partial side effects, commit point, compensation/idempotency:
resource cleanup and ownership:
result/error/context exposed to caller and telemetry:
grace, escalation, process shutdown and test bound:

Multiple sources are normal. Cancellation should be idempotent and converge on one state machine; “exactly one place may cancel” is not a realistic requirement.

Interruption protocol

Thread.interrupt() sets interrupt status and may cause an interruptible blocking operation to terminate according to its API. Many methods throwing InterruptedException clear status when they do so. Thread.interrupted() reads and clears the current thread's status; isInterrupted() does not clear it.

Choose handling by boundary:

There are more than “exactly two legal responses.” The invariant is that an owned signal is handled, propagated or deliberately consumed at its terminal owner, with cleanup and semantics preserved. Logging and continuing ordinary work is usually a bug.

CPU and polling loops

Check cancellation at a cadence derived from maximum allowed latency and per-iteration cost—not necessarily every iteration. Avoid allocating/logging on every check. Include nested library work, parallel subtasks and safepoint behavior in the bound. Thread.onSpinWait() does not check interrupt or relinquish ownership.

Blocking and resource cancellation

Interrupt behavior is exact-API/provider/thread/version-specific. Classify each blocking point:

• specified interruptible wait throwing InterruptedException;
• channel operation that closes/wakes with channel-specific exception;
• operation whose owning socket/stream/session must be closed/aborted;
• API with its own cancel handle/deadline (Statement.cancel, HTTP request future, subscription);
• native/foreign call with library-specific interruption or no cooperative path;
• monitor acquisition, lock acquisition, future join/get, sleep/park and condition wait, each with distinct semantics.

Do not use a timeless table saying every classic socket/native call ignores interruption. Virtual threads and JDK/provider implementations have evolved. Read the exact API contract, run a positive control on the target, and prefer owner-initiated close only when close semantics and connection reuse are acceptable.

Futures and stages

• Future.cancel(false) can prevent execution before start; if already running, it does not request interruption and work may continue even though the Future is cancelled.
• Future.cancel(true) requests interruption when implementation can identify a running task; termination still depends on task/API cooperation.
• CompletableFuture.cancel(boolean) treats cancellation as exceptional completion; its mayInterruptIfRunning argument has no effect in the class contract. It is not automatically a handle to the computation that will complete it.
• wait timeouts such as get(timeout) bound the waiter, not the producer. orTimeout completes the stage exceptionally but does not universally stop underlying work.

Bridge cancellation explicitly when adapting callback/client APIs: retain the underlying handle, propagate terminal state both directions once, and resolve completion-versus-cancel races.

Structured ownership

Executors/scopes can track tasks and signal unfinished work during shutdown/failure, but cannot make noncooperative operations terminate. Structured-concurrency APIs are versioned preview/finalization work; verify target API. Define join/deadline/failure policy, scope close behavior, subtask interruptibility and what resource aborts are triggered.

State consistency

Mark cancellation points around semantic commit:

before side effect -> abandon safely
during staged local mutation -> rollback/complete invariant
after external request sent -> outcome may be unknown; cancellation cannot undo it
after durable commit -> return cancellation may hide success; reconcile/idempotency needed

Never assume interruption rolls back a database transaction, remote call, file write or message. Cancellation can produce an unknown outcome and must compose with idempotency/recovery.

Observability

Measure by operation/resource:

cancellation requested / acknowledged / terminated
request-to-observation and request-to-resource-release latency
reason/source and race winner (bounded labels)
work completed after caller deadline/cancel
resources still held and downstream request still active
cleanup failures and forced shutdown/escalation

Do not count Future exceptional completion as task termination without a terminal-work signal.

Tests

Select cases for the execution/resource boundaries actually involved. Coordinate entry and release with latches/barriers or a controllable server, not sleeps; bound every wait and provide an independent teardown path. Isolate deliberately uncooperative work in a child process so a failing termination assertion cannot hang the test suite.

• cancel before start, during CPU work, at each blocking point and after semantic commit;
• multiple sources racing with normal completion/failure;
• swallowed/cleared interrupt and task/framework boundary translation;
• noninterruptible provider/native call and owner close/abort;
• resource released/reusable versus deliberately closed;
• partial write/transaction/message/remote unknown outcome;
• executor/scope shutdown and process grace expiry;
• virtual/platform thread and supported JDK/provider variants;
• cancellation storm under load, ensuring residual work does not amplify overload.

Anti-patterns

Definition of done

• All sources/races converge on one idempotent terminal-state model.
• Every CPU/blocking/native/resource layer has a tested stop/abort path or explicit bound.
• Interrupt propagation/translation/restoration is correct at each ownership boundary.
• Partial/unknown side effects and commit races have recovery semantics.
• Termination and resource release—not only caller return—meet measured bounds.
• Applicable shutdown, load, target JDK/provider and residual-work tests pass; omitted or unavailable checks are stated explicitly.

Report the owning boundary, observed signal and terminal/release evidence, unresolved outcome, and one validating test for each proposed fix. Distinguish measured termination latency from a configured deadline or an untested estimate.

References

• Interrupt handling by boundary — read when reviewing a catch/finally boundary, deferred interruption or executor shutdown.
• Blocking operations and cancellation adapters — read when a blocking provider, external cancel handle or resource abort must stop work.
• Thread interruption API
• Future
• CompletableFuture