Class ScopedValueMisuseDetector
java.lang.Object
se.deversity.asynctest.diagnostics.ScopedValueMisuseDetector
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
ScopedValuevia nestedwhere().run()with conflicting values (not always an error, but often unintentional in frameworks) - Cross-scope leak — A
ScopedValueaccessed in a scope where it was not bound; this throwsNoSuchElementExceptionat runtime if not guarded withisBound() - 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 throwNoSuchElementException
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
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic classReport of ScopedValue misuse analysis. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionanalyze()Analyze all recorded ScopedValue events for misuse patterns.voidEnds the round's bindings.voidrecordBindingEntered(String variableName, Thread thread) Record that aScopedValue.where(sv, val).run()binding has been entered on the current thread.voidrecordBindingExited(String variableName, Thread thread) Record that a binding scope has been exited (therun()lambda returned).voidrecordGetCalled(String variableName, Thread thread) Record thatScopedValue.get()(orisBound()) was called.
-
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
Record that aScopedValue.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
Record that a binding scope has been exited (therun()lambda returned).- Parameters:
variableName- a descriptive name for the ScopedValuethread- the current thread
-
recordGetCalled
Record thatScopedValue.get()(orisBound()) 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 ScopedValuethread- the current thread
-
analyze
Analyze all recorded ScopedValue events for misuse patterns.- Returns:
- a report describing detected issues
-