Summary

Update the methods defined by java.lang.ScopedValue and java.lang.ScopedValue.Carrier to more clearly specify when StructureViolationException is thrown. Also make it clear that any exception/error thrown by an operation is propagated.

Problem

The following methods are specified, via their method descriptions, to throw StructureViolationException when a structure violation is detected:

ScopedValue.runWhere
ScopedValue.callWhere
ScopedValue.getWhere
ScopedValue.Carrier.run
ScopedValue.Carrier.call
ScopedValue.Carrier.get

The description isn't easy to read, and the methods don't have a @throws StructureViolationException.

Solution

Re-word the paragraph that describes when StructureViolationException is thrown

Add @throws StructureViolationException to the 6 methods.

Add a statement to make it clear that the methods propagate any exception thrown by the operation.

Specification

Specdiff is unable to deal with this change and is truncating the diff of ScopedValue, making the output useless.

The change to all methods is the same:

--- a/src/java.base/share/classes/java/lang/ScopedValue.java
+++ b/src/java.base/share/classes/java/lang/ScopedValue.java
@@ -394,19 +394,20 @@ public final class ScopedValue<T> {
          * to its value in the current thread.
          * When the operation completes (normally or with an exception), each scoped value
          * in the mapping will revert to being unbound, or revert to its previous value
-         * when previously bound, in the current thread.
+         * when previously bound, in the current thread. If {@code op} completes with an
+         * exception then it propagated by this method.
          *
-         * <p> Scoped values are intended to be used in a <em>structured manner</em>.
-         * If {@code op} creates a {@link StructuredTaskScope} but does not {@linkplain
-         * StructuredTaskScope#close() close} it, then exiting {@code op} causes the
-         * underlying construct of each {@code StructuredTaskScope} created in the
-         * dynamic scope to be closed. This may require blocking until all child threads
-         * have completed their sub-tasks. The closing is done in the reverse order that
-         * they were created. Once closed, {@link StructureViolationException} is thrown.
+         * <p> Scoped values are intended to be used in a <em>structured manner</em>. If code
+         * invoked directly or indirectly by the operation creates a {@link StructuredTaskScope}
+         * but does not {@linkplain StructuredTaskScope#close() close} it, then it is detected
+         * as a <em>structure violation</em> when the operation completes (normally or with an
+         * exception). In that case, the underlying construct of the {@code StructuredTaskScope}
+         * is closed and {@link StructureViolationException} is thrown.
          *
          * @param op the operation to run
          * @param <R> the type of the result of the operation
          * @return the result
+         * @throws StructureViolationException if a structure violation is detected