daniellansun commented on code in PR #3298:
URL: https://github.com/apache/groovy/pull/3298#discussion_r4571201925
##########
src/main/java/groovy/concurrent/AsyncScope.java:
##########
@@ -100,6 +109,9 @@ public interface AsyncScope extends AutoCloseable {
* Closes the scope, waiting for all child tasks to complete.
* If any child failed and fail-fast is enabled, remaining children
* are cancelled and the first failure is rethrown.
+ *
+ * @apiNote The failure is rethrown as itself, so this method can throw a
+ * checked exception it does not declare; see the class documentation.
Review Comment:
The new `@apiNote` here and on the class header is very clear for Java
callers. Three small points we might optionally mention or refine (either here
or in the class `@apiNote`):
1. **Direct `try-with-resources` usage (`try (var scope =
AsyncScope.create())`):** Unlike `withScope` (which guards `if (closeError !=
bodyError)`), `javac` desugars `try-with-resources` into an unconditional
`primary.addSuppressed(closeError)` (JLS §14.20.3 / OpenJDK `JDK-8317229`). If
caller code inside `try (var scope = AsyncScope.create())` awaits a failed
child of `scope` and lets that exception escape the `try` block,
`scope.close()` will rethrow the exact same unwrapped instance and trigger
`IllegalArgumentException: Self-suppression not permitted` unless `withScope`
is used instead.
2. **Worker-originated `InterruptedException`:** When a child task throws
`InterruptedException` on a worker thread, `close()` now rethrows that
`InterruptedException` onto the calling thread while
`Thread.currentThread().isInterrupted()` remains `false` (distinct from
interruption of the calling thread itself).
3. **Cross-referencing on `withScope` overloads:** Adding a short `@apiNote`
pointer on the `withScope` methods back to the class-level note would also let
IDE hover tooltips on `AsyncScope.withScope(...)` surface this sneaky-throw
caveat (and JLS §11.2.3 implications) directly to pure Java callers of
`groovy-concurrent-java`.
--
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]