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]

Reply via email to