daniellansun commented on code in PR #3298:
URL: https://github.com/apache/groovy/pull/3298#discussion_r4571272458
##########
src/main/java/groovy/concurrent/AsyncScope.java:
##########
@@ -46,6 +46,15 @@
* task completes exceptionally, all sibling tasks are cancelled
* immediately. The first failure becomes the primary exception;
* subsequent failures are added as suppressed exceptions.
+ * <p>
+ * A failure is rethrown as the exception the task threw, including a
+ * checked exception, as {@code await} does.
+ *
+ * @apiNote {@link #close()} and {@code withScope} declare no checked
+ * exceptions but can still throw one. Java callers that need to handle a
+ * checked failure should catch {@code Exception} and test its type, as
+ * the Java compiler rejects a {@code catch} of a checked exception the
+ * try block does not declare.
Review Comment:
Nice addition—documenting the sneaky-throw behavior explicitly via
`@apiNote` on `AsyncScope` and `close()` is very helpful for pure Java callers
of `groovy-concurrent-java`, where `javac` rejects catching undeclared checked
exceptions per JLS §11.2.3.
Two small optional doc refinements if helpful:
1. **Cross-referencing on `withScope` overloads:** Adding a short `@apiNote`
pointer on the `withScope` methods back to the class-level note would let IDE
hover tooltips on `AsyncScope.withScope(...)` surface this caveat directly to
Java callers.
2. **Contrasting `withScope` with Java `try-with-resources`:** When a scope
body and a child task fail with (or `await`) the same exception instance,
`withScope` safely guards `if (closeError != bodyError)` at line 186, whereas
Java's `try (var scope = AsyncScope.create())` emits an unconditional
`primary.addSuppressed(closeError)` (`JDK-8317229`) and would throw
`IllegalArgumentException: Self-suppression not permitted` now that `close()`
rethrows the raw failure unwrapped.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]