馃摑 docs(util): correct write and break guarantees - #762
Merged
Merged
Conversation
gaborbernat
force-pushed
the
docs-soft-marker-limits
branch
from
October 1, 2026 21:25
6f337ba to
c9271f8
Compare
gaborbernat
approved these changes
Oct 1, 2026
A peer that reads between two os.write calls in write_all sees a prefix of the record. Remove the claim that the loop makes the record atomic. break_lock_file leaves a live marker under its break name to keep the holder's file, but the lock path ends up empty and a third process can acquire alongside that holder. Say so in the docstring and test comment, and remove three references to a soft read/write marker break the code does not have. Claude-Session: https://claude.ai/code/session_0185Ga4wvPxDBm7NwTthKqYf
gaborbernat
force-pushed
the
docs-soft-marker-limits
branch
from
October 1, 2026 21:32
c9271f8 to
e0fa94c
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
We documented
write_allas keeping the marker "atomic in the process and kernel view". A peer that reads between twoos.writecalls sees a prefix of the record, andSoftFileLockwaits two seconds before it breaks a malformed marker for that reason. I reworded the docstring to say the loop completes the record and each caller has to tolerate partial reads.We wrote in the
break_lock_filedocstring, and in the comment intest_break_lock_file_preserves_file_when_mtime_advanced, that keeping a live marker under its break name prevents two holders. Processes A and B both judge a dead holder's marker stale, and B breaks it and acquires. A renames B's live marker aside and, seeing a new inode, leaves it under the break name; that empties the lock path for C to acquire while B runs. B and C both hold the lock.StrictSoftFileLockhas no such race because an operator'sforce_breakis its sole way to remove another process's claim, as the strict claims section ofdocs/concepts.rstdescribes.We referred to "the soft read/write marker break" three times in the
break_lock_filedocstring, but_soft_rw/has no rename-based break, so I removed those references.I changed docstrings and one test comment, so I labeled the PR
skip newsin place of adding a changelog fragment.