Skip to content

Commit 4fb2294

Browse files
ctruedenclaude
andcommitted
Make cancellation thread interruption
SciJava has accumulated several cancellation APIs -- Cancelable in SciJava Common and ImageJ Ops, the cancel half of task.Task, Appose's cancel() -- and SciJava Ops shipped with none of them. Rather than invent a fourth, use the platform's: interruption as the mechanism, and Future.cancel(true) as the API a caller holds. Every scheme is cooperative, so that is not what distinguishes them; composition is. An ambient thread flag is honored by code we did not write, including every interruptible JDK blocking call, while an isCanceled() interface only works for code that knows about it, and a cancellation token pollutes every signature while still being unable to abort a blocking call. Note that an interrupt carries no reason: Thread.interrupt() takes no argument and the JDK constructs InterruptedException with a null message. A reason belongs to whoever requested cancellation, not to the exception. Implemented here: - Progress.checkCancellation() throws CancellationException, restoring the interrupt flag first so code further up the stack still sees it. Progress.update() calls it, so anything already reporting progress is cancellable with no new API and no extra parameter. Ops cannot throw InterruptedException, being plain Functions, hence the unchecked CancellationException, which is also what Future.get() throws. - DataHandles.copy checks the flag once per block and throws InterruptedIOException, which is an IOException -- so the signature is unchanged -- with bytesTransferred set to the partial copy. The granularity matches the task.isCanceled() check it replaces; a read already under way cannot be aborted, since plain streams are not interruptible. Cancelable is therefore not ported at all. The docs record the design, its accepted limits (CompletableFuture.cancel does not interrupt; the flag does not inherit to worker threads; native code ignores interrupts), and why Appose's explicit cancel() stays as it is: interruption cannot cross a process boundary. Still to do: Parallelization and TaskExecutor must propagate cancellation to worker futures, since the interrupt flag does not inherit. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013gJpzGd3ksbME4CN6Tu2ni
1 parent 851b0e6 commit 4fb2294

6 files changed

Lines changed: 381 additions & 9 deletions

File tree

‎docs/migration-plan.md‎

Lines changed: 96 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -219,6 +219,92 @@ has always had. The cost to a plugin module is one line:
219219
opens my.plugins.impl to org.scijava.context;
220220
```
221221

222+
### Cancellation is thread interruption
223+
224+
SciJava has invented several cancellation APIs over the years — `Cancelable`
225+
in SJC's `module` package and across ImageJ Ops, the cancel half of
226+
`task.Task`, and Appose's `cancel()`. SciJava Ops deliberately shipped without
227+
any of them. The replacement is the platform's own mechanism, not a fourth
228+
invention.
229+
230+
- **Mechanism:** thread interruption. Every interruptible JDK blocking call
231+
already honors it — `Thread.sleep`, `Object.wait`, `BlockingQueue`,
232+
`Lock.lockInterruptibly`, NIO channels — and Java 21's
233+
`StructuredTaskScope` cancels its subtasks by interrupting them, so this
234+
stays current.
235+
- **Client API:** `ExecutorService.submit()` → `Future.cancel(true)`. That is
236+
what a caller holds: cancellation, completion and result in one object every
237+
Java developer already knows.
238+
- **No `Cancelable`, and no cancellation token parameter.** Every scheme is
239+
cooperative, so that is not the differentiator; composition is. An ambient
240+
thread flag is honored by code we did not write, while an `isCanceled()`
241+
interface only works for code that knows about it, and a token pollutes
242+
every signature while still being unable to abort a JDK blocking call.
243+
244+
**An interrupt carries no reason.** `Thread.interrupt()` takes no argument and
245+
the JDK constructs `InterruptedException` with a null message, so a reason
246+
cannot ride along. A reason belongs to the requesting side — the `Future`, or
247+
the caller's own record of why it cancelled — not to the exception.
248+
249+
#### Cooperating in code that cannot throw
250+
251+
Ops are `Function`, `Computers.Arity*` and similar, whose methods declare no
252+
checked exceptions, so an op cannot throw `InterruptedException`. The idiom:
253+
254+
```java
255+
if (Thread.interrupted()) { // NB: this clears the flag...
256+
Thread.currentThread().interrupt(); // ...so restore it
257+
throw new CancellationException("op cancelled");
258+
}
259+
```
260+
261+
`java.util.concurrent.CancellationException` is unchecked and is what
262+
`Future.get()` already throws for a cancelled task, so callers see one type.
263+
264+
**`Progress.update()` is the checkpoint.** Ops that do long work already call
265+
it periodically, so making it check for interruption gives cancellation with
266+
no new API, no extra parameter, and no per-op work. Progress and cancellation
267+
are both ambient and thread-scoped; they belong on the same rail. An op that
268+
reports no progress is not cancellable, which is honest, and a nudge toward
269+
reporting progress.
270+
271+
#### Known limits, accepted deliberately
272+
273+
- `CompletableFuture.cancel()` does **not** interrupt the running thread; it
274+
only completes the future exceptionally. Expose `ExecutorService` futures
275+
where cancellation must reach a compute loop.
276+
- The interrupt flag is thread-bound and **does not inherit**, unlike
277+
`Progress`, which is an `InheritableThreadLocal`. So `Parallelization` and
278+
`TaskExecutor` must propagate cancellation to worker futures deliberately.
279+
That is the one piece of real work this design implies.
280+
- Plain `InputStream`/`FileInputStream` reads are not interruptible; only NIO
281+
channels are. Blocking I/O therefore aborts between operations, not during
282+
one.
283+
- Native code ignores interrupts: a long OpenCV call cannot be cancelled
284+
mid-call.
285+
- The common practical hazard is library code that catches
286+
`InterruptedException` and swallows it. The rule is always: propagate it, or
287+
restore the flag.
288+
289+
#### Across a process boundary
290+
291+
Interruption cannot cross one, so **Appose's explicit `cancel()` is correct as
292+
it stands**. In-process: interruption. Across processes: an explicit protocol.
293+
294+
#### Consequences for this migration
295+
296+
1. `Cancelable` is **not ported** (see [migration.md](migration.md)).
297+
2. The Phase 3 execution layer hands back a `Future`; module and op execution
298+
submit to an executor, and cancellation is `future.cancel(true)`.
299+
3. `Progress.update()` checks for interruption and throws
300+
`CancellationException`.
301+
4. `Parallelization` propagates cancellation to its workers.
302+
5. `DataHandles.copy` checks once per block and throws
303+
`java.io.InterruptedIOException`, which is an `IOException` — so it fits
304+
the existing signature — and whose `bytesTransferred` field reports the
305+
partial copy. The granularity is per-block, identical to the
306+
`task.isCanceled()` check it replaces.
307+
222308
### Logging
223309

224310
SLF4J, used directly, as `scijava-types` and `scijava-ops-engine` already do.
@@ -253,9 +339,9 @@ No application context required by anything in this phase.
253339
were **not** left behind as deprecated aliases, which the repository's
254340
current adoption level permits.
255341
- The test for membership: *if a class can implement it without knowing
256-
about any SciJava framework, it is SPI.* `Cancelable` fails that test
257-
(cancellation concerns a running thing — it belongs with the execution
258-
layer, near `Progress`/`Task`), as do `Validated`, `BasicDetails`,
342+
about any SciJava framework, it is SPI.* `Cancelable` fails that test —
343+
and is not ported at all, since cancellation is thread interruption — as
344+
do `Validated`, `BasicDetails`,
259345
`UIDetails` and `Plugin` (metadata bags for the plugin/module layer) and
260346
`Initializable` (lifecycle, so it belongs with `scijava-context`).
261347
- `Named` exposes `String name()` only. Mutability is a separate contract;
@@ -317,10 +403,11 @@ No application context required by anything in this phase.
317403
position and buffers of one open stream, so `create()` instantiates a
318404
fresh one per call. SciJava Common got this from `WrapperService`; here
319405
it is explicit, and tested.
320-
- **Open question:** `DataHandles.copy` took a `Task`, which carried both
321-
progress *and cancellation*; its replacement `LongConsumer` carries only
322-
progress. If cancellable copies are wanted, that needs a deliberate
323-
mechanism rather than falling out of the progress type.
406+
- `DataHandles.copy` took a `Task`, which carried both progress *and
407+
cancellation*; its replacement `LongConsumer` carries only progress.
408+
Cancellation is thread interruption instead — see the cancellation
409+
section — so `copy` checks the flag once per block and throws
410+
`InterruptedIOException`.
324411
- Still to port: `io.nio`.
325412
- **`scijava-events`** (new, `org.scijava.events`): a clean-room event bus,
326413
no context, designed for typed topics and weak-reference subscribers. Not a
@@ -390,7 +477,8 @@ No application context required by anything in this phase.
390477
useful it runs the other way, `ops-engine` → execution layer.
391478
- **Execution module** (name TBD): pre/postprocessor chains, input resolution,
392479
a `@Parameter` equivalent, and a runner — built on `scijava-struct`.
393-
`Cancelable`'s replacement lives here.
480+
Cancellation needs nothing here: the runner hands back a `Future`, and
481+
cancelling it interrupts the worker.
394482
- **Commands:** a struct, plus menu metadata, plus `run`. Commands and Ops
395483
remain separate concepts sharing this layer.
396484
- **Scripting:** `javax.script` is not general enough. GraalVM's Truffle

‎docs/migration.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -79,7 +79,7 @@ A **dropped** row is a successful outcome, not a gap.
7979
| `Locatable` | deferred — its only content was a default implementation needing `common3.Classes.location`, which `scijava-spi` cannot depend on | open |
8080
| `Typed` | deferred to the plugin layer — no consumer yet, and `Class<T> type()` collides with `GenericTyped.type()` | open |
8181
| `Initializable` | `scijava-context` (Phase 2) — a lifecycle hook, not an SPI contract | planned |
82-
| `Cancelable` | execution layer (Phase 3) — cancellation concerns a running thing | planned |
82+
| `Cancelable` | **not ported** — cancellation is thread interruption, and the client API is `Future.cancel(true)`. See the cancellation section of [migration-plan.md](migration-plan.md) | dropped |
8383
| `ItemIO` | `org.scijava.struct.ItemIO` | ported |
8484
| `ItemVisibility` | input harvesting (Phase 4) | open |
8585
| `Context`, `Contextual`, `AbstractContextual`, `NullContextException`, `NoSuchServiceException` | `org.scijava.context` (Phase 2) | planned |

‎scijava-io3/src/main/java/org/scijava/io3/handle/DataHandles.java‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@
3131

3232
import java.io.DataOutput;
3333
import java.io.IOException;
34+
import java.io.InterruptedIOException;
3435
import java.io.UTFDataFormatException;
3536
import java.util.ArrayList;
3637
import java.util.Comparator;
@@ -187,6 +188,9 @@ public static long copy(final DataHandle<Location> in,
187188
* @param progress notified with the running total, or null for none
188189
* @param bufferSize the size of the copy buffer
189190
* @return the number of bytes copied
191+
* @throws InterruptedIOException if the thread is interrupted, with
192+
* {@link InterruptedIOException#bytesTransferred} set to what had
193+
* been copied
190194
*/
191195
public static long copy(final DataHandle<Location> in,
192196
final DataHandle<Location> out, final long length,
@@ -195,6 +199,20 @@ public static long copy(final DataHandle<Location> in,
195199
final byte[] buffer = new byte[bufferSize];
196200
long totalRead = 0;
197201
while (true) {
202+
// NB: cancellation is thread interruption. The check is per block, the
203+
// same granularity as the Task.isCanceled() check this replaces; a read
204+
// already under way cannot be aborted, since plain streams are not
205+
// interruptible.
206+
if (Thread.interrupted()) {
207+
// NB: Thread.interrupted() clears the flag, so restore it: callers
208+
// further up the stack must still see that this thread was cancelled.
209+
Thread.currentThread().interrupt();
210+
final InterruptedIOException exc = new InterruptedIOException(
211+
"Copy cancelled");
212+
// NB: int, per the field's type; saturate rather than wrap around.
213+
exc.bytesTransferred = (int) Math.min(totalRead, Integer.MAX_VALUE);
214+
throw exc;
215+
}
198216
final int r;
199217
// NB: do not read past the requested length.
200218
if (length > 0 && totalRead + bufferSize > length) {

‎scijava-io3/src/test/java/org/scijava/io3/handle/DataHandlesTest.java‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,17 +33,23 @@
3333
import static org.junit.jupiter.api.Assertions.assertEquals;
3434
import static org.junit.jupiter.api.Assertions.assertFalse;
3535
import static org.junit.jupiter.api.Assertions.assertInstanceOf;
36+
import static org.junit.jupiter.api.Assertions.assertNotNull;
3637
import static org.junit.jupiter.api.Assertions.assertNotSame;
3738
import static org.junit.jupiter.api.Assertions.assertNull;
3839
import static org.junit.jupiter.api.Assertions.assertTrue;
3940

4041
import java.io.File;
4142
import java.io.IOException;
43+
import java.io.InterruptedIOException;
4244
import java.nio.charset.StandardCharsets;
4345
import java.nio.file.Files;
4446
import java.nio.file.Path;
4547
import java.util.ArrayList;
4648
import java.util.List;
49+
import java.util.concurrent.CountDownLatch;
50+
import java.util.concurrent.TimeUnit;
51+
import java.util.concurrent.atomic.AtomicBoolean;
52+
import java.util.concurrent.atomic.AtomicReference;
4753

4854
import org.junit.jupiter.api.Test;
4955
import org.junit.jupiter.api.io.TempDir;
@@ -153,6 +159,64 @@ public void testCopyReportsProgress(@TempDir final Path dir)
153159
assertEquals(data.length, progress.get(progress.size() - 1));
154160
}
155161

162+
/**
163+
* Cancellation is thread interruption: a copy stops at the next block
164+
* boundary, reports how far it got, and leaves the interrupt flag set for
165+
* whoever is further up the stack.
166+
*/
167+
@Test
168+
@SuppressWarnings("unchecked")
169+
public void testCopyIsCancelledByInterruption(@TempDir final Path dir)
170+
throws Exception
171+
{
172+
final File in = dir.resolve("in.bin").toFile();
173+
Files.write(in.toPath(), new byte[20000]);
174+
final File out = dir.resolve("out.bin").toFile();
175+
176+
final AtomicReference<InterruptedIOException> thrown =
177+
new AtomicReference<>();
178+
final AtomicBoolean flagStillSet = new AtomicBoolean();
179+
final CountDownLatch started = new CountDownLatch(1);
180+
181+
final Thread worker = new Thread(() -> {
182+
try (final DataHandle<Location> source = (DataHandle<Location>) //
183+
(DataHandle<?>) DataHandles.get().create(new FileLocation(in));
184+
final DataHandle<Location> target = (DataHandle<Location>) //
185+
(DataHandle<?>) DataHandles.get().create(new FileLocation(out)))
186+
{
187+
started.countDown();
188+
// NB: one byte at a time, so the copy is still running when the
189+
// interrupt lands.
190+
DataHandles.copy(source, target, 0, bytes -> {
191+
try {
192+
Thread.sleep(1);
193+
}
194+
catch (final InterruptedException exc) {
195+
Thread.currentThread().interrupt();
196+
}
197+
}, 1);
198+
}
199+
catch (final InterruptedIOException exc) {
200+
thrown.set(exc);
201+
flagStillSet.set(Thread.currentThread().isInterrupted());
202+
}
203+
catch (final IOException exc) {
204+
throw new AssertionError(exc);
205+
}
206+
});
207+
worker.start();
208+
assertTrue(started.await(5, TimeUnit.SECONDS));
209+
Thread.sleep(50);
210+
worker.interrupt();
211+
worker.join(5000);
212+
213+
final InterruptedIOException exc = thrown.get();
214+
assertNotNull(exc, "copy was not cancelled");
215+
assertTrue(exc.bytesTransferred > 0, "no partial progress reported");
216+
assertTrue(exc.bytesTransferred < 20000, "copy ran to completion");
217+
assertTrue(flagStillSet.get(), "the interrupt flag must be restored");
218+
}
219+
156220
/** Where two handles support a location, the higher priority one wins. */
157221
@Test
158222
public void testPriorityOrdering() {

‎scijava-progress/src/main/java/org/scijava/progress/Progress.java‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@
3030
package org.scijava.progress;
3131

3232
import java.util.*;
33+
import java.util.concurrent.CancellationException;
3334
import java.util.concurrent.CopyOnWriteArrayList;
3435
import java.util.function.Consumer;
3536

@@ -258,13 +259,47 @@ public static void update(long elements) {
258259
*
259260
* @param numElements the number of elements completed in the current stage.
260261
* @param task the {@link Task} to update
262+
* @throws CancellationException if this thread has been interrupted
261263
* @see Task#update(long)
264+
* @see #checkCancellation()
262265
*/
263266
public static void update(final long numElements, final Task task) {
267+
checkCancellation();
264268
task.update(numElements);
265269
pingListeners(task);
266270
}
267271

272+
/**
273+
* Throws {@link CancellationException} if this thread has been interrupted.
274+
* <p>
275+
* Cancellation in SciJava is thread interruption: a caller holding a
276+
* {@link java.util.concurrent.Future} cancels with
277+
* {@code future.cancel(true)}, which interrupts the worker thread. Work that
278+
* cannot throw {@link InterruptedException} - an {@code Op} implementing a
279+
* plain {@link java.util.function.Function}, for instance - cooperates by
280+
* calling this method periodically.
281+
* </p>
282+
* <p>
283+
* {@link #update()} calls it already, so anything that reports progress is
284+
* cancellable without further effort. Call it directly in a long loop that
285+
* reports no progress.
286+
* </p>
287+
* <p>
288+
* The interrupt flag is restored before throwing, so that code further up
289+
* the stack still sees that this thread was cancelled.
290+
* </p>
291+
*
292+
* @throws CancellationException if this thread has been interrupted
293+
*/
294+
public static void checkCancellation() {
295+
// NB: Thread.interrupted() clears the flag, hence the restore below.
296+
if (Thread.interrupted()) {
297+
Thread.currentThread().interrupt();
298+
throw new CancellationException("Cancelled: " + Thread.currentThread()
299+
.getName());
300+
}
301+
}
302+
268303
/**
269304
* Sets the status of the current {@link Task}, pinging any interested
270305
* {@link Consumer}s.

0 commit comments

Comments
 (0)