Class SharedMemorySegmentRaceDetector
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.
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
-
Nested Class Summary
Nested Classes -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionanalyze()Evaluate the observed state and produce a report.voidCloses the round in progress.voidrecordAccess(@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.voidrecordAccess(@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.voidrecordClose(@Nullable Object segment, @Nullable String label) Record that the segment's arena has been closed.
-
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 anullguard.- Parameters:
segment- theMemorySegmentaccessed, typedObject(null-safe)label- human-readable label for triage (may benull)offset- byte offset of the accesslength- byte length of the accesswrite-truefor a write,falsefor a readthread- 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- theMemorySegmentaccessed, typedObject(null-safe)label- human-readable label for triage (may benull)offset- byte offset of the accesslength- byte length of the accesswrite-truefor a write,falsefor a readthread- the accessing threadguard- label of the monitor held during the access, ornullif unguarded
-
recordClose
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, typedObject(null-safe)label- human-readable label for triage (may benull)
-
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
-