Class ScopedValueMisuseDetector

java.lang.Object
se.deversity.asynctest.diagnostics.ScopedValueMisuseDetector

public class ScopedValueMisuseDetector extends Object
Detects misuse of Java 21+ ScopedValue.

ScopedValue is the preferred alternative to ThreadLocal for virtual thread workloads. It provides immutable, inheritable, scope-bounded context that works correctly with structured concurrency. Its API is safe by design — a value is only accessible inside a ScopedValue.where(sv, val).run(task) block.

Issues detected:

  • Mutation attempt — Attempting to re-bind an already-bound ScopedValue via nested where().run() with conflicting values (not always an error, but often unintentional in frameworks)
  • Cross-scope leak — A ScopedValue accessed in a scope where it was not bound; this throws NoSuchElementException at runtime if not guarded with isBound()
  • Excessive bindings per task — More than a configurable threshold of distinct ScopedValues bound in a single call chain (design smell)
  • Unbound get() call — get() called without a prior binding on this thread / scope, which will throw NoSuchElementException

Usage:


 private static final ScopedValue<String> USER_ID = ScopedValue.newInstance();

 @AsyncTest(threads = 10, useVirtualThreads = true, includes = DetectorType.SCOPED_VALUE)
 void testScopedValueUsage() {
     var detector = AsyncTestContext.scopedValueMisuseDetector();
     String svName = "USER_ID";

     detector.recordBindingEntered(svName, Thread.currentThread());
     ScopedValue.where(USER_ID, "user-" + Thread.currentThread().threadId()).run(() -> {
         detector.recordGetCalled(svName, Thread.currentThread());
         String userId = USER_ID.get(); // safe — we're inside the binding
         processRequest(userId);
         detector.recordBindingExited(svName, Thread.currentThread());
     });
 }
 
Since:
0.7.0
  • Constructor Details

    • ScopedValueMisuseDetector

      public ScopedValueMisuseDetector()
  • Method Details

    • markInvocationStart

      public void markInvocationStart()
      Ends the round's bindings. A binding whose round threw before it was exited stays recorded, and a pooled platform worker reused in the next round carried it there, where its own binding read as a nested rebind (#1419). The runner calls this once the previous round's workers have finished.
      Since:
      1.14.4
    • recordBindingEntered

      public void recordBindingEntered(String variableName, Thread thread)
      Record that a ScopedValue.where(sv, val).run() binding has been entered on the current thread.
      Parameters:
      variableName - a descriptive name for the ScopedValue (e.g. field name)
      thread - the current thread
    • recordBindingExited

      public void recordBindingExited(String variableName, Thread thread)
      Record that a binding scope has been exited (the run() lambda returned).
      Parameters:
      variableName - a descriptive name for the ScopedValue
      thread - the current thread
    • recordGetCalled

      public void recordGetCalled(String variableName, Thread thread)
      Record that ScopedValue.get() (or isBound()) was called. If the variable is not currently bound on this thread, an unbound-get issue is recorded.
      Parameters:
      variableName - a descriptive name for the ScopedValue
      thread - the current thread
    • analyze

      Analyze all recorded ScopedValue events for misuse patterns.
      Returns:
      a report describing detected issues