Class FileChannelPositionRaceDetector

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

public final class FileChannelPositionRaceDetector extends Object
Detects a FileChannel / SeekableByteChannel whose implicit position one thread sets and then relies on while another thread's call can move it in between.

Why it matters. FileChannel is documented as safe for use by multiple concurrent threads, and it runs one operation involving the position at a time, so a single FileChannel.read(ByteBuffer) or FileChannel.write(ByteBuffer) always completes whole, at the offset the cursor held when it started. What the channel cannot make atomic is a sequence of calls: a thread that calls FileChannel.position(long) (or reads FileChannel.position()) and then reads or writes relying on that offset has nothing to stop another thread's read, write or position call from landing between the two. The I/O then happens at an offset its thread did not choose: a read returns bytes from the wrong region, and a write lands somewhere other than where it was aimed, over whatever is there. A probe on JDK 21 and 26 (8 threads, 5,000 operations each) read the wrong bytes about 1,500 times in 40,000 with an unguarded position(n) then read(buffer), and lost nothing with unguarded self-contained read(buffer) or write(buffer) calls, which is why those alone are no finding (#819).

The positional variants FileChannel.read(ByteBuffer, long) and FileChannel.write(ByteBuffer, long) do not touch the shared position — each call is self-contained and safe to invoke concurrently on the same channel, and they are recorded through recordPositionalAccess(java.lang.Object, java.lang.String).

The safe patterns are: use the positional read(buffer, position)/ write(buffer, position) overloads, hold one lock across the seek and the I/O on every thread that uses the channel, open one FileChannel per thread, or switch to AsynchronousFileChannel, whose read/write methods always take an explicit position.

What is judged. A position call a thread records opens a seek, and every read or write that thread makes on the same channel after it, in the same invocation round and until its next seek on that channel, is I/O relying on it: each starts where the seek and the calls since left the cursor, so a second read after one seek relies on it as much as the first, and so does a read after a seek on another channel. A thread keeps an open seek on up to four channels at once, and a seek on one more forgets the one sought longest ago (#835). Any other call, such as a truncate, relies on nothing and leaves the seek open (#831). A call that neither uses nor moves the position (size, force, transferTo, transferFrom, map, lock, tryLock) is not recorded at all, so it is no call that can land inside a sequence either; any other name counts, as truncate does (#835). The verdict is SelfGuard's, taken per invocation round, with each sequence's I/O as the write and every other implicit-position call as a read: a round is reported when a thread completed a sequence and another thread made an implicit-position call that no lock common to both and no happens-before edge keeps out of it. The channel's own monitor counts as a lock, as does one declared through HeldLocks; a read lock guards the self-contained calls and not a sequence, since it admits other readers. A lock guards a sequence only if its thread held it without a break from the seek to the I/O: one released and taken again between them lets another thread's call in, and is not counted for the I/O (#831). That is decided from HeldLocks, so it covers declared locks and, with the agent attached, woven synchronized blocks and Lock calls; the channel's own monitor left and entered again in code the agent does not weave still reads as held across, since nothing reports its release. For the same reason a monitor that code the agent does not weave held at the seek counts at the I/O whenever the thread holds it there, woven re-entries of it included (#835): an unwoven synchronized (channel) around the sequence guards it with a woven block around the read inside it, and an unwoven block around the seek, left before a woven block around the read, reads as held across. A woven block around the seek inside an unwoven one, left and entered again before the read, still reads as a break, since nothing tells the outer hold from none. A position call is always a seek, never I/O relying on the call before it: the operation name cannot tell position() from position(long), and even a position() after a write starts the next sequence as often as it asks where the write landed. So a self-contained call relying on where an earlier one left the cursor, such as a write(buffer) followed by position() to learn where it landed, is not a sequence; reading it as one would report every thread that seeks afresh under its lock after an earlier call.

Usage:


 var d = new FileChannelPositionRaceDetector();
 d.recordImplicitPositionAccess(channel, "position");  // the seek
 d.recordImplicitPositionAccess(channel, "read");      // the read relying on it
 d.recordPositionalAccess(channel, "read");            // explicit offset, safe
 
Since:
1.7.0
  • Constructor Details

    • FileChannelPositionRaceDetector

      public FileChannelPositionRaceDetector()
  • Method Details

    • recordImplicitPositionAccess

      public void recordImplicitPositionAccess(Object channel, String operation)
      Record an implicit-position operation: one of read, write, position, or truncate. These operations use or move the channel's shared cursor. transferTo and transferFrom do neither, by the FileChannel javadoc, so they are not recorded here.

      An operation whose name starts with position, for position(long) or position(), is a seek. One whose name starts with read or write, made by the calling thread on the same channel after a seek, in the same invocation round and until its next seek on that channel, is I/O relying on that seek. A name starting with size, force, transferTo, transferFrom, map, lock or tryLock neither uses nor moves the position and is ignored. Any other name, truncate among them, relies on nothing and leaves an open seek open. Only a seek with I/O relying on it can be reported, and only when another thread's implicit-position call can land inside it; every call but an ignored one is recorded so that it can be that other call.

      Parameters:
      channel - the channel instance (null-safe)
      operation - short name of the operation, e.g. "read"
    • markInvocationStart

      public void markInvocationStart()
      Starts a new invocation round: every thread's open seeks are forgotten, and their slots let go of the channels.

      A seek is relied on only within its round, which the round clock already decides, but the slot of a pooled worker held the channel reference until that worker sought again, if it ever did (#831). No worker is running when the runner calls this; a seek that a thread the test left running records meanwhile may stay listed or be forgotten, and either way is not relied on in a later round.

      Since:
      1.12.3
    • recordPositionalAccess

      public void recordPositionalAccess(Object channel, String operation)
      Record a positional operation: read(buffer, position) or write(buffer, position). These take an explicit offset, never touch the shared cursor, and are safe to call concurrently — this detector never flags them as a race.
      Parameters:
      channel - the channel instance (null-safe)
      operation - short name of the operation, e.g. "read"
    • analyze

      Analyses what has been recorded about the observation and builds the report for it.
      Returns:
      the findings this detector collected during the run