Scoped values API

Author: Andrew Haley

src/java.base/share/classes/java/lang/ScopedValue.java

@@ -75,34 +75,34 @@
  *     // @link substring="newInstance" target="#newInstance" :
  *     private static final ScopedValue<String> NAME = ScopedValue.newInstance();
  *
- *     // @link substring="runWhere" target="#runWhere(ScopedValue, Object, Runnable)" :
- *     ScopedValue.runWhere(NAME, "duke", () -> doSomething());
+ *     // @link substring="run" target="Carrier#run(Runnable)" :
+ *     ScopedValue.where(NAME, "duke").run(() -> doSomething());
  * }
  * Code executed directly or indirectly by {@code doSomething}, with access to the field
  * {@code NAME}, can invoke {@code NAME.get()} to read the value "{@code duke}". {@code
  * NAME} is bound while executing the {@code run} method. It reverts to being unbound when
  * the {@code run} method completes.
  *
- * <p> The example using {@code runWhere} invokes a method that does not return a result.
- * The {@link #callWhere(ScopedValue, Object, CallableOp) callWhere} method can be used
+ * <p> The example using {@code run} invokes a method that does not return a result.
+ * The {@link Carrier#call(CallableOp) call} method can be used
  * to invoke a method that returns a result.
- * In addition, {@code ScopedValue} defines the {@link #where(ScopedValue, Object)} method
+ * {@code ScopedValue} defines the {@link #where(ScopedValue, Object)} method
  * for cases where multiple mappings (of {@code ScopedValue} to value) are accumulated
  * in advance of calling a method with all {@code ScopedValue}s bound to their value.
  *
  * <h2>Bindings are per-thread</h2>
  *
- * A {@code ScopedValue} binding to a value is per-thread. Invoking {@code xxxWhere}
+ * A {@code ScopedValue} binding to a value is per-thread. Invoking {@code run}
  * executes a method with a {@code ScopedValue} bound to a value for the current thread.
  * The {@link #get() get} method returns the value bound for the current thread.
  *
  * <p> In the example, if code executed by one thread invokes this:
  * {@snippet lang=java :
- *     ScopedValue.runWhere(NAME, "duke1", () -> doSomething());
+ *     ScopedValue.where(NAME, "duke1").run(() -> doSomething());
  * }
  * and code executed by another thread invokes:
  * {@snippet lang=java :
- *     ScopedValue.runWhere(NAME, "duke2", () -> doSomething());
+ *     ScopedValue.where(NAME, "duke2").run(() -> doSomething());
  * }
  * then code in {@code doSomething} (or any method that it calls) invoking {@code NAME.get()}
  * will read the value "{@code duke1}" or "{@code duke2}", depending on which thread is
@@ -129,7 +129,7 @@
  * <p> In the above example, suppose that code executed by {@code doSomething} binds
  * {@code NAME} to a new value with:
  * {@snippet lang=java :
- *     ScopedValue.runWhere(NAME, "duchess", () -> doMore());
+ *     ScopedValue.where(NAME, "duchess").run(() -> doMore());
  * }
  * Code executed directly or indirectly by {@code doMore()} that invokes {@code
  * NAME.get()} will read the value "{@code duchess}". When {@code doMore()} completes
@@ -157,7 +157,7 @@
  * {@snippet lang=java :
  *     private static final ScopedValue<String> NAME = ScopedValue.newInstance();
 
- *     ScopedValue.runWhere(NAME, "duke", () -> {
+ *     ScopedValue.where(NAME, "duke").run(() -> {
  *         // @link substring="open" target="StructuredTaskScope#open(Policy)" :
  *         try (var scope = StructuredTaskScope.open(policy)) {
  *
@@ -414,7 +414,6 @@ public <T> T get(ScopedValue<T> key) {
          * @return the result
          * @throws StructureViolationException if a structure violation is detected
          * @throws X if {@code op} completes with an exception
-         * @see ScopedValue#callWhere(ScopedValue, Object, CallableOp)
          * @since 23
          */
         public <R, X extends Throwable> R call(CallableOp<? extends R, X> op) throws X {
@@ -463,7 +462,6 @@ private <R, X extends Throwable> R runWith(Snapshot newSnapshot, CallableOp<R, X
          *
          * @param op the operation to run
          * @throws StructureViolationException if a structure violation is detected
-         * @see ScopedValue#runWhere(ScopedValue, Object, Runnable)
          */
         public void run(Runnable op) {
             Objects.requireNonNull(op);
@@ -533,77 +531,6 @@ public static <T> Carrier where(ScopedValue<T> key, T value) {
         return Carrier.of(key, value);
     }
 
-    /**
-     * Calls a value-returning operation with a {@code ScopedValue} bound to a value
-     * in the current thread. When the operation completes (normally or with an
-     * exception), the {@code ScopedValue} will revert to being unbound, or revert to
-     * its previous value 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
-     * 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.
-     *
-     * @implNote
-     * This method is implemented to be equivalent to:
-     * {@snippet lang=java :
-     *     // @link substring="call" target="Carrier#call(CallableOp)" :
-     *     ScopedValue.where(key, value).call(op);
-     * }
-     *
-     *
-     *
-     * @param key the {@code ScopedValue} key
-     * @param value the value, can be {@code null}
-     * @param <T> the type of the value
-     * @param <R> the result type
-     * @param <X> type of the exception thrown by the operation
-     * @param op the operation to call
-     * @return the result
-     * @throws StructureViolationException if a structure violation is detected
-     * @throws X if the operation completes with an exception
-     * @since 23
-     */
-    public static <T, R, X extends Throwable> R callWhere(ScopedValue<T> key,
-                                                          T value,
-                                                          CallableOp<? extends R, X> op) throws X {
-        return where(key, value).call(op);
-    }
-
-    /**
-     * Run an operation with a {@code ScopedValue} bound to a value in the current
-     * thread. When the operation completes (normally or with an exception), the
-     * {@code ScopedValue} will revert to being unbound, or revert to its previous value
-     * 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
-     * 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.
-     *
-     * @implNote
-     * This method is implemented to be equivalent to:
-     * {@snippet lang=java :
-     *     // @link substring="run" target="Carrier#run(Runnable)" :
-     *     ScopedValue.where(key, value).run(op);
-     * }
-     *
-     * @param key the {@code ScopedValue} key
-     * @param value the value, can be {@code null}
-     * @param <T> the type of the value
-     * @param op the operation to call
-     * @throws StructureViolationException if a structure violation is detected
-     */
-    public static <T> void runWhere(ScopedValue<T> key, T value, Runnable op) {
-        where(key, value).run(op);
-    }
-
     private ScopedValue() {
         this.hash = generateKey();
     }

src/java.base/share/classes/java/util/concurrent/StructuredTaskScope.java

@@ -275,8 +275,8 @@
  *     // @link substring="newInstance" target="ScopedValue#newInstance()" :
  *     private static final ScopedValue<String> USERNAME = ScopedValue.newInstance();
  *
- *     // @link substring="callWhere" target="ScopedValue#callWhere" :
- *     Result result = ScopedValue.callWhere(USERNAME, "duke", () -> {
+ *     // @link substring="callWhere" target="ScopedValue#where" :
+ *     Result result = ScopedValue.where(USERNAME, "duke").call(() -> {
  *
  *         try (var scope = StructuredTaskScope.open(Joiner.awaitAllSuccessfulOrThrow())) {
  *

src/java.base/share/classes/javax/security/auth/Subject.java

@@ -436,7 +436,7 @@ public static <T> T callAs(final Subject subject,
         Objects.requireNonNull(action);
         if (!SharedSecrets.getJavaLangAccess().allowSecurityManager()) {
             try {
-                return ScopedValue.callWhere(SCOPED_SUBJECT, subject, action::call);
+                return ScopedValue.where(SCOPED_SUBJECT, subject).call(action::call);
             } catch (Exception e) {
                 throw new CompletionException(e);
             }