Class FileChannelPositionRaceDetector
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
-
Nested Class Summary
Nested Classes -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionanalyze()Analyses what has been recorded about the observation and builds the report for it.voidStarts a new invocation round: every thread's open seeks are forgotten, and their slots let go of the channels.voidrecordImplicitPositionAccess(Object channel, String operation) Record an implicit-position operation: one ofread,write,position, ortruncate.voidrecordPositionalAccess(Object channel, String operation) Record a positional operation:read(buffer, position)orwrite(buffer, position).
-
Constructor Details
-
FileChannelPositionRaceDetector
public FileChannelPositionRaceDetector()
-
-
Method Details
-
recordImplicitPositionAccess
Record an implicit-position operation: one ofread,write,position, ortruncate. These operations use or move the channel's shared cursor.transferToandtransferFromdo neither, by theFileChanneljavadoc, so they are not recorded here.An operation whose name starts with
position, forposition(long)orposition(), is a seek. One whose name starts withreadorwrite, 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 withsize,force,transferTo,transferFrom,map,lockortryLockneither uses nor moves the position and is ignored. Any other name,truncateamong 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
Record a positional operation:read(buffer, position)orwrite(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
-