You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@groovy.apache.org by su...@apache.org on 2026/05/01 08:11:39 UTC

(groovy) branch master updated: Add missing javadoc for `ScopedLocal`

This is an automated email from the ASF dual-hosted git repository.

asf-gitbox-commits pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/groovy.git


The following commit(s) were added to refs/heads/master by this push:
     new 9d59d71efb Add missing javadoc for `ScopedLocal`
9d59d71efb is described below

commit 9d59d71efb0a5b15dd4d31e333a64033620a526c
Author: Daniel Sun <su...@apache.org>
AuthorDate: Fri May 1 17:02:11 2026 +0900

    Add missing javadoc for `ScopedLocal`
---
 .../apache/groovy/runtime/async/ScopedLocal.java   | 220 +++++++++++++++++++++
 1 file changed, 220 insertions(+)

diff --git a/src/main/java/org/apache/groovy/runtime/async/ScopedLocal.java b/src/main/java/org/apache/groovy/runtime/async/ScopedLocal.java
index 85043ffaad..3901025152 100644
--- a/src/main/java/org/apache/groovy/runtime/async/ScopedLocal.java
+++ b/src/main/java/org/apache/groovy/runtime/async/ScopedLocal.java
@@ -72,17 +72,52 @@ import java.util.logging.Logger;
  * @since 6.0.0
  */
 public abstract class ScopedLocal<T> {
+    /** Logger used for backend-detection diagnostics. */
     private static final Logger LOGGER = Logger.getLogger(ScopedLocal.class.getName());
+
+    /** Standard message used when an unbound scoped-local is queried without a default supplier. */
     private static final String UNBOUND_MESSAGE =
             "ScopedLocal is not bound and has no initial supplier";
 
+    /** Cached reflective view of the optional JDK {@code ScopedValue} API. */
     private static final ScopedValueBindings SCOPED_VALUE_BINDINGS = ScopedValueBindings.detect();
 
+    /**
+     * Whether the runtime provides a usable {@code ScopedValue} backend.
+     * <p>
+     * This field has package visibility so the test suite can verify backend
+     * selection without duplicating the detection logic.
+     */
     static final boolean SCOPED_VALUE_AVAILABLE = SCOPED_VALUE_BINDINGS.isAvailable();
+
+    /**
+     * Method handle for {@code ScopedValue.newInstance()}, adapted to the erased
+     * signature {@code ()Object} for stable {@code invokeExact} usage.
+     */
     static final MethodHandle SV_NEW_INSTANCE = SCOPED_VALUE_BINDINGS.newInstanceHandle();
+
+    /**
+     * Method handle for {@code ScopedValue.where(ScopedValue, Object)}, adapted
+     * to the erased signature {@code (Object, Object)Object}.
+     */
     static final MethodHandle SV_WHERE = SCOPED_VALUE_BINDINGS.whereHandle();
+
+    /**
+     * Method handle for {@code ScopedValue.get()}, adapted to the erased
+     * signature {@code (Object)Object}.
+     */
     static final MethodHandle SV_GET = SCOPED_VALUE_BINDINGS.getHandle();
+
+    /**
+     * Method handle for {@code ScopedValue.isBound()}, adapted to the erased
+     * signature {@code (Object)boolean}.
+     */
     static final MethodHandle SV_IS_BOUND = SCOPED_VALUE_BINDINGS.isBoundHandle();
+
+    /**
+     * Method handle for {@code ScopedValue.Carrier.run(Runnable)}, adapted to
+     * the erased signature {@code (Object, Runnable)void}.
+     */
     static final MethodHandle CARRIER_RUN = SCOPED_VALUE_BINDINGS.carrierRunHandle();
 
     /**
@@ -196,8 +231,23 @@ public abstract class ScopedLocal<T> {
         ScopedLocal.where(this, value).run(action);
     }
 
+    /**
+     * Applies {@code value} as the active binding for the duration of
+     * {@code action}, restoring any prior state when the action finishes.
+     *
+     * @param value  the value to bind; may be {@code null}
+     * @param action the action to execute with the binding active
+     */
     abstract void bind(Object value, Runnable action);
 
+    /**
+     * Rethrows {@code t} without wrapping it, preserving the original runtime
+     * type while satisfying the compiler's checked-exception rules.
+     *
+     * @param <E> the inferred exception type
+     * @param t   the throwable to rethrow
+     * @throws E always, as the original throwable
+     */
     @SuppressWarnings("unchecked")
     static <E extends Throwable> void sneakyThrow(Throwable t) throws E {
         throw (E) t;
@@ -210,10 +260,22 @@ public abstract class ScopedLocal<T> {
      * @since 6.0.0
      */
     public static final class Carrier {
+        /** Scoped-local key represented by this carrier node. */
         private final ScopedLocal<?> key;
+
+        /** Value bound to {@link #key} for this carrier node; may be {@code null}. */
         private final Object value;
+
+        /** Previous carrier node, allowing multiple bindings to be chained immutably. */
         private final Carrier prev;
 
+        /**
+         * Creates a carrier node for one binding in the immutable carrier chain.
+         *
+         * @param key   the scoped-local key for this node
+         * @param value the value bound for this node; may be {@code null}
+         * @param prev  the previously accumulated carrier chain, or {@code null}
+         */
         private Carrier(ScopedLocal<?> key, Object value, Carrier prev) {
             this.key = key;
             this.value = value;
@@ -261,6 +323,12 @@ public abstract class ScopedLocal<T> {
             return value;
         }
 
+        /**
+         * Composes the binding stack represented by this carrier around the
+         * supplied action and runs the resulting scoped execution.
+         *
+         * @param action the terminal action to run once all bindings are active
+         */
         private void execute(Runnable action) {
             Runnable scopedAction = action;
             for (Carrier carrier = this; carrier != null; carrier = carrier.prev) {
@@ -273,21 +341,39 @@ public abstract class ScopedLocal<T> {
         }
     }
 
+    /**
+     * {@link ThreadLocal}-backed implementation used when the platform does not
+     * provide {@code ScopedValue}.
+     */
     private static final class ThreadLocalImpl<T> extends ScopedLocal<T> {
+        /** Sentinel representing the absence of both an explicit binding and a cached initial value. */
         private static final Object UNSET = new Object();
+
+        /** Sentinel that lets the delegate distinguish a bound {@code null} from {@link #UNSET}. */
         private static final Object NULL_SENTINEL = new Object();
 
+        /** Per-thread storage for the current binding or cached initial value. */
         private final ThreadLocal<Object> delegate = ThreadLocal.withInitial(() -> UNSET);
+
+        /** Optional supplier used to lazily initialize a per-thread default value. */
         private final Supplier<? extends T> initialSupplier;
 
+        /** Creates an instance without a default supplier. */
         private ThreadLocalImpl() {
             this.initialSupplier = null;
         }
 
+        /**
+         * Creates an instance whose unbound reads are initialized from
+         * {@code initialSupplier} once per thread.
+         *
+         * @param initialSupplier supplies the per-thread default value
+         */
         private ThreadLocalImpl(Supplier<? extends T> initialSupplier) {
             this.initialSupplier = initialSupplier;
         }
 
+        /** {@inheritDoc} */
         @Override
         public T get() {
             Object value = delegate.get();
@@ -300,6 +386,7 @@ public abstract class ScopedLocal<T> {
             throw new NoSuchElementException(UNBOUND_MESSAGE);
         }
 
+        /** {@inheritDoc} */
         @Override
         public T orElse(T other) {
             Object value = delegate.get();
@@ -312,6 +399,7 @@ public abstract class ScopedLocal<T> {
             return other;
         }
 
+        /** {@inheritDoc} */
         @Override
         public <X extends Throwable> T orElseThrow(Supplier<? extends X> exceptionSupplier) throws X {
             Objects.requireNonNull(exceptionSupplier, "exceptionSupplier must not be null");
@@ -325,11 +413,13 @@ public abstract class ScopedLocal<T> {
             throw exceptionSupplier.get();
         }
 
+        /** {@inheritDoc} */
         @Override
         public boolean isBound() {
             return delegate.get() != UNSET || initialSupplier != null;
         }
 
+        /** {@inheritDoc} */
         @Override
         void bind(Object value, Runnable action) {
             Object previous = delegate.get();
@@ -345,38 +435,73 @@ public abstract class ScopedLocal<T> {
             }
         }
 
+        /**
+         * Computes, stores, and returns this thread's lazily initialized value.
+         *
+         * @return the initialized value, which may be {@code null}
+         */
         private T initializeAndCache() {
             T initialValue = initialSupplier.get();
             delegate.set(encode(initialValue));
             return initialValue;
         }
 
+        /**
+         * Decodes an internal sentinel-backed representation into the user value.
+         *
+         * @param value the stored value
+         * @return the decoded user value, possibly {@code null}
+         */
         @SuppressWarnings("unchecked")
         private T decode(Object value) {
             return value == NULL_SENTINEL ? null : (T) value;
         }
 
+        /**
+         * Encodes {@code null} values using a sentinel so they can be stored in
+         * the {@link ThreadLocal} without being confused with an uninitialized slot.
+         *
+         * @param value the user value, possibly {@code null}
+         * @return the encoded storage form
+         */
         private Object encode(Object value) {
             return value == null ? NULL_SENTINEL : value;
         }
     }
 
+    /**
+     * {@code ScopedValue}-backed implementation used on runtimes that expose the
+     * JDK 25 API, with an auxiliary {@link ThreadLocal} only for
+     * {@link #withInitial(Supplier)} semantics.
+     */
     private static final class ScopedValueImpl<T> extends ScopedLocal<T> {
+        /** Sentinel that preserves explicit {@code null} bindings across the erased backend API. */
         private static final Object NULL_SENTINEL = new Object();
 
+        /** Backend-specific {@code ScopedValue} instance, stored as {@code Object} for cross-JDK compatibility. */
         private final Object scopedValue;
+
+        /** Optional per-thread fallback used only to cache values from {@link #withInitial(Supplier)}. */
         private final ThreadLocal<T> fallback;
 
+        /** Creates an instance without a default supplier. */
         private ScopedValueImpl() {
             this.scopedValue = newScopedValue();
             this.fallback = null;
         }
 
+        /**
+         * Creates an instance with lazily initialized per-thread fallback values
+         * for unbound reads.
+         *
+         * @param initialSupplier supplies the fallback value for each thread
+         */
         private ScopedValueImpl(Supplier<? extends T> initialSupplier) {
             this.scopedValue = newScopedValue();
             this.fallback = ThreadLocal.withInitial(initialSupplier::get);
         }
 
+        /** {@inheritDoc} */
         @Override
         public T get() {
             if (isScopedBindingPresent()) {
@@ -388,6 +513,7 @@ public abstract class ScopedLocal<T> {
             throw new NoSuchElementException(UNBOUND_MESSAGE);
         }
 
+        /** {@inheritDoc} */
         @Override
         public T orElse(T other) {
             if (isScopedBindingPresent()) {
@@ -399,6 +525,7 @@ public abstract class ScopedLocal<T> {
             return other;
         }
 
+        /** {@inheritDoc} */
         @Override
         public <X extends Throwable> T orElseThrow(Supplier<? extends X> exceptionSupplier) throws X {
             Objects.requireNonNull(exceptionSupplier, "exceptionSupplier must not be null");
@@ -411,11 +538,13 @@ public abstract class ScopedLocal<T> {
             throw exceptionSupplier.get();
         }
 
+        /** {@inheritDoc} */
         @Override
         public boolean isBound() {
             return isScopedBindingPresent() || fallback != null;
         }
 
+        /** {@inheritDoc} */
         @Override
         void bind(Object value, Runnable action) {
             try {
@@ -426,6 +555,12 @@ public abstract class ScopedLocal<T> {
             }
         }
 
+        /**
+         * Returns whether the underlying {@code ScopedValue} currently has an
+         * explicit binding on this thread.
+         *
+         * @return {@code true} if a scoped binding is active
+         */
         private boolean isScopedBindingPresent() {
             try {
                 return (boolean) SV_IS_BOUND.invokeExact(scopedValue);
@@ -435,6 +570,11 @@ public abstract class ScopedLocal<T> {
             }
         }
 
+        /**
+         * Reads the raw value from the underlying {@code ScopedValue}.
+         *
+         * @return the stored raw value, possibly the internal null sentinel
+         */
         private Object readScopedValue() {
             try {
                 return SV_GET.invokeExact(scopedValue);
@@ -444,15 +584,33 @@ public abstract class ScopedLocal<T> {
             }
         }
 
+        /**
+         * Decodes the erased backend value into the user-visible value.
+         *
+         * @param value the raw backend value
+         * @return the decoded value, possibly {@code null}
+         */
         @SuppressWarnings("unchecked")
         private T decode(Object value) {
             return value == NULL_SENTINEL ? null : (T) value;
         }
 
+        /**
+         * Encodes a user value for storage in the erased backend API.
+         *
+         * @param value the user value, possibly {@code null}
+         * @return the encoded backend value
+         */
         private Object encode(Object value) {
             return value == null ? NULL_SENTINEL : value;
         }
 
+        /**
+         * Creates a new backend {@code ScopedValue} instance through the adapted
+         * method handle.
+         *
+         * @return the newly created backend object
+         */
         private static Object newScopedValue() {
             try {
                 return SV_NEW_INSTANCE.invokeExact();
@@ -462,14 +620,34 @@ public abstract class ScopedLocal<T> {
         }
     }
 
+    /**
+     * Holder for optional method-handle bindings to the JDK {@code ScopedValue}
+     * API, allowing this class to link lazily and remain binary-compatible with
+     * earlier Java versions.
+     */
     private static final class ScopedValueBindings {
+        /** Whether all required {@code ScopedValue} entry points were discovered successfully. */
         private final boolean available;
+
+        /** Adapted handle for {@code ScopedValue.newInstance()}. */
         private final MethodHandle newInstance;
+
+        /** Adapted handle for {@code ScopedValue.where(ScopedValue, Object)}. */
         private final MethodHandle where;
+
+        /** Adapted handle for {@code ScopedValue.get()}. */
         private final MethodHandle get;
+
+        /** Adapted handle for {@code ScopedValue.isBound()}. */
         private final MethodHandle isBound;
+
+        /** Adapted handle for {@code ScopedValue.Carrier.run(Runnable)}. */
         private final MethodHandle carrierRun;
 
+        /**
+         * Creates a binding container for either the detected backend handles or
+         * the sentinel unavailable state.
+         */
         private ScopedValueBindings(boolean available, MethodHandle newInstance, MethodHandle where,
                                     MethodHandle get, MethodHandle isBound, MethodHandle carrierRun) {
             this.available = available;
@@ -480,6 +658,12 @@ public abstract class ScopedLocal<T> {
             this.carrierRun = carrierRun;
         }
 
+        /**
+         * Detects the availability of finalized {@code ScopedValue} support and,
+         * when present, prepares adapted method handles for exact invocation.
+         *
+         * @return the discovered bindings, or an unavailable marker on failure
+         */
         private static ScopedValueBindings detect() {
             if (Runtime.version().feature() < 25) {
                 return unavailable();
@@ -518,30 +702,66 @@ public abstract class ScopedLocal<T> {
             }
         }
 
+        /**
+         * Returns a binding container representing the absence of a usable
+         * {@code ScopedValue} backend.
+         *
+         * @return an unavailable binding descriptor
+         */
         private static ScopedValueBindings unavailable() {
             return new ScopedValueBindings(false, null, null, null, null, null);
         }
 
+        /**
+         * Returns whether the runtime supports the {@code ScopedValue} backend.
+         *
+         * @return {@code true} when the adapted handles are available
+         */
         private boolean isAvailable() {
             return available;
         }
 
+        /**
+         * Returns the adapted handle for creating new backend instances.
+         *
+         * @return the creation handle, or {@code null} when unavailable
+         */
         private MethodHandle newInstanceHandle() {
             return newInstance;
         }
 
+        /**
+         * Returns the adapted handle for binding a scoped value.
+         *
+         * @return the binding handle, or {@code null} when unavailable
+         */
         private MethodHandle whereHandle() {
             return where;
         }
 
+        /**
+         * Returns the adapted handle for reading a scoped value.
+         *
+         * @return the read handle, or {@code null} when unavailable
+         */
         private MethodHandle getHandle() {
             return get;
         }
 
+        /**
+         * Returns the adapted handle for checking whether a scoped value is bound.
+         *
+         * @return the bound-check handle, or {@code null} when unavailable
+         */
         private MethodHandle isBoundHandle() {
             return isBound;
         }
 
+        /**
+         * Returns the adapted handle for running a backend carrier.
+         *
+         * @return the carrier-run handle, or {@code null} when unavailable
+         */
         private MethodHandle carrierRunHandle() {
             return carrierRun;
         }