Class ScopeResultEscapeDetector

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

public final class ScopeResultEscapeDetector extends Object
Detects results of a 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
  • Constructor Details

    • ScopeResultEscapeDetector

      public ScopeResultEscapeDetector()
      Creates a detector with no recorded scopes.
  • Method Details

    • recordScopeOpened

      public void recordScopeOpened(String scopeId, Thread owner)
      Record a scope opening and who owns it.
      Parameters:
      scopeId - the scope's identifier, unique per open
      owner - the thread opening the scope
    • recordJoinCompleted

      public void recordJoinCompleted(String scopeId)
      Record that join() returned, which is where the results become readable.
      Parameters:
      scopeId - the scope's identifier
    • recordResultHandle

      public void recordResultHandle(Object handle, String label, String scopeId)
      Record a handle onto a scope's results - the List<Subtask<T>> a joiner returned, or a single Subtask.
      Parameters:
      handle - the list or subtask, tracked by identity
      label - a label identifying it in the report
      scopeId - the scope that produced it
    • recordHandleRead

      public void recordHandleRead(Object handle, Thread thread)
      Record a read of a result handle - iterating the list, or calling Subtask.get().
      Parameters:
      handle - the list or subtask, tracked by identity
      thread - the reading thread
    • recordHandlePublished

      public void recordHandlePublished(Object handle, Thread thread)
      Record the handle being stored somewhere another thread can reach it.
      Parameters:
      handle - the list or subtask, tracked by identity
      thread - the publishing thread
    • recordHandleMutation

      public void recordHandleMutation(Object handle, Thread thread)
      Record an attempt to modify the returned result list.
      Parameters:
      handle - the list, tracked by identity
      thread - the mutating thread
    • recordScopeClosed

      public void recordScopeClosed(String scopeId)
      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