Class ScopeResultEscapeDetector
StructuredTaskScope outliving the scope that produced them - the
hazard JEP 525 made easy to reach by returning collections instead of streams.
In JDK 25 the built-in joiners handed back a Stream<Subtask<T>>. A stream is lazy and
single-use, so keeping one past close() tended to fail loudly and early. JDK 26 changed
allSuccessfulOrThrow() and allUntil(...) to return a List, which is the
ergonomic improvement everyone wanted and also a handle that looks perfectly safe to store in a
field, hand to another thread, or read after the try-with-resources block has ended:
List<Subtask<Order>> results;
try (var scope = StructuredTaskScope.open(Joiner.<Order>allSuccessfulOrThrow())) {
scope.fork(this::fetchA);
results = scope.join();
}
return results.get(0).get(); // the scope is gone; this is outside the structure
The point of structured concurrency is that a subtask does not outlive its scope. A result
handle read after close() has no happens-before edge to anything the scope did on the
way out, and a handle read by a thread that never owned the scope has none to the subtasks that
filled it either - join() on the owner thread is where that edge is established.
StructuredTaskScopeMisuseDetector covers reading a result too early: before
join(), or after a timeout cancelled the subtask. This detector covers reading one
too late, or on the wrong thread. The two are disjoint by construction: nothing here
fires until join() has completed or the scope has closed.
Issues detected:
- Read after close - a result list or subtask read after its scope closed. The structure that guaranteed the value is complete no longer exists.
- Read off the owner thread - a result handle read by a thread other than the one
that opened the scope and called
join(). That thread has no happens-before edge to the subtask writes the list points at. - Published before join - the handle stored into a field or shared collection before
join()completed, which lets another thread reach it while subtasks are still running. - Mutation attempted - a write to the returned list. It is unmodifiable, so the write throws; reaching for it at all means the caller believed it owned a private copy.
Usage inside @AsyncTest(includes = DetectorType.SCOPE_RESULT_ESCAPE):
var d = AsyncTestContext.scopeResultEscapeDetector();
d.recordScopeOpened("scope-1", Thread.currentThread());
...
d.recordJoinCompleted("scope-1");
d.recordResultHandle(results, "orderResults", "scope-1");
d.recordScopeClosed("scope-1");
d.recordHandleRead(results, Thread.currentThread()); // after close: reported
- Since:
- 1.9.7
-
Nested Class Summary
Nested Classes -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionanalyze()Analyses the recorded result handles and builds the report.voiddisable()Turn recording off; already-recorded state is kept.voidenable()Turn recording back on.voidrecordHandleMutation(Object handle, Thread thread) Record an attempt to modify the returned result list.voidrecordHandlePublished(Object handle, Thread thread) Record the handle being stored somewhere another thread can reach it.voidrecordHandleRead(Object handle, Thread thread) Record a read of a result handle - iterating the list, or callingSubtask.get().voidrecordJoinCompleted(String scopeId) Record thatjoin()returned, which is where the results become readable.voidrecordResultHandle(Object handle, String label, String scopeId) Record a handle onto a scope's results - theList<Subtask<T>>a joiner returned, or a singleSubtask.voidrecordScopeClosed(String scopeId) Record a scope closing, which ends the window in which its results are valid.voidrecordScopeOpened(String scopeId, Thread owner) Record a scope opening and who owns it.
-
Constructor Details
-
ScopeResultEscapeDetector
public ScopeResultEscapeDetector()Creates a detector with no recorded scopes.
-
-
Method Details
-
recordScopeOpened
Record a scope opening and who owns it.- Parameters:
scopeId- the scope's identifier, unique per openowner- the thread opening the scope
-
recordJoinCompleted
Record thatjoin()returned, which is where the results become readable.- Parameters:
scopeId- the scope's identifier
-
recordResultHandle
Record a handle onto a scope's results - theList<Subtask<T>>a joiner returned, or a singleSubtask.- Parameters:
handle- the list or subtask, tracked by identitylabel- a label identifying it in the reportscopeId- the scope that produced it
-
recordHandleRead
Record a read of a result handle - iterating the list, or callingSubtask.get().- Parameters:
handle- the list or subtask, tracked by identitythread- the reading thread
-
recordHandlePublished
Record the handle being stored somewhere another thread can reach it.- Parameters:
handle- the list or subtask, tracked by identitythread- the publishing thread
-
recordHandleMutation
Record an attempt to modify the returned result list.- Parameters:
handle- the list, tracked by identitythread- the mutating thread
-
recordScopeClosed
Record a scope closing, which ends the window in which its results are valid.- Parameters:
scopeId- the scope's identifier
-
disable
public void disable()Turn recording off; already-recorded state is kept. -
enable
public void enable()Turn recording back on. -
analyze
Analyses the recorded result handles and builds the report.- Returns:
- the findings this detector collected during the run
-