Class SharedMemorySegmentRaceDetector

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

public final class SharedMemorySegmentRaceDetector extends Object
Detects unsynchronized concurrent access to overlapping regions of a shared MemorySegment (FFM API, JEP 454, final in JDK 22), and access to a segment after its arena has been closed.

Arena.ofShared() lifts the confinement check that ConfinedArenaThreadEscapeDetector watches, and lifting it is the whole problem: a shared segment can be touched from any thread, but plain get/set on a segment carries no memory-model guarantee. Two threads writing overlapping bytes race exactly like two threads writing a plain field, with no volatile semantics and no tearing guarantee above 8 bytes. The FFM API's answer is a VarHandle with an atomic access mode, or ordinary mutual exclusion.

Trust tier. Byte-range overlap alone cannot tell a race from correctly locked sharing, which is the same limit that makes the older access-pattern detectors report "verify synchronization" rather than "this is broken". This detector narrows that gap with an optional lock model: pass a guard label to recordAccess(Object, String, long, long, boolean, Thread, String) naming the monitor held during the access, and overlapping accesses that agree on a non-null guard are treated as synchronized and stay silent. Findings therefore split into two tiers, and the wording says which one you are reading:

  • overlap with conflicting guards, or a mix of guarded and unguarded access — a genuine defect, reported at HIGH;
  • overlap with no guard recorded anywhere — a prompt to verify, reported at MEDIUM, because the test may simply not have told the detector about its locks.
Use-after-close is neither: it is unconditionally CRITICAL.

The parameter types are Object rather than java.lang.foreign.MemorySegment so this class compiles on the library's JDK 21 baseline, where the FFM API is still preview.

Usage inside @AsyncTest(includes = DetectorType.SHARED_MEMORY_SEGMENT_RACE):


 var d = AsyncTestContext.sharedMemorySegmentRaceDetector();
 try (Arena arena = Arena.ofShared()) {
     MemorySegment seg = arena.allocate(4096);
     // ... from several threads ...
     seg.set(JAVA_INT, 0, value);
     d.recordAccess(seg, "ringBuffer", 0, 4, true, Thread.currentThread());  // unguarded write
 }
 
Since:
1.8.0
  • Constructor Details

    • SharedMemorySegmentRaceDetector

      public SharedMemorySegmentRaceDetector()
  • Method Details

    • markInvocationStart

      public void markInvocationStart()
      Closes the round in progress. The runner ends a round by awaiting its workers and starts the next by submitting fresh tasks, so an access in round n happens-before every access in round n+1 and the two cannot overlap in time whatever bytes they touch.
      Since:
      1.11.2
    • recordAccess

      public void recordAccess(@Nullable Object segment, @Nullable String label, long offset, long length, boolean write, @Nullable Thread thread)
      Record an access to a byte range of a shared segment, with no lock information. Equivalent to calling the seven-argument overload with a null guard.
      Parameters:
      segment - the MemorySegment accessed, typed Object (null-safe)
      label - human-readable label for triage (may be null)
      offset - byte offset of the access
      length - byte length of the access
      write - true for a write, false for a read
      thread - the accessing thread
    • recordAccess

      public void recordAccess(@Nullable Object segment, @Nullable String label, long offset, long length, boolean write, @Nullable Thread thread, @Nullable String guard)
      Record an access to a byte range of a shared segment, naming the lock held for its duration. Overlapping accesses that agree on a non-null guard are treated as correctly synchronized and produce no finding, which is what lets this detector distinguish a race from safe sharing instead of flagging both.
      Parameters:
      segment - the MemorySegment accessed, typed Object (null-safe)
      label - human-readable label for triage (may be null)
      offset - byte offset of the access
      length - byte length of the access
      write - true for a write, false for a read
      thread - the accessing thread
      guard - label of the monitor held during the access, or null if unguarded
    • recordClose

      public void recordClose(@Nullable Object segment, @Nullable String label)
      Record that the segment's arena has been closed. Every access recorded after this point is a use-after-free against freed native memory.
      Parameters:
      segment - the segment whose arena closed, typed Object (null-safe)
      label - human-readable label for triage (may be null)
    • analyze

      Evaluate the observed state and produce a report. Idempotent: calling it N times on quiescent state yields N identical reports.
      Returns:
      the report of overlapping unsynchronized accesses and use-after-close accesses