Skip to content

馃摑 docs(util): correct write and break guarantees - #762

Merged
gaborbernat merged 1 commit into
tox-dev:mainfrom
pralav-25:docs-soft-marker-limits
Oct 1, 2026
Merged

gaborbernat merged 1 commit into
tox-dev:mainfrom
pralav-25:docs-soft-marker-limits

Conversation

@pralav-25

@pralav-25 pralav-25 commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor

We documented write_all as keeping the marker "atomic in the process and kernel view". A peer that reads between two os.write calls sees a prefix of the record, and SoftFileLock waits 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_file docstring, and in the comment in test_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. StrictSoftFileLock has no such race because an operator's force_break is its sole way to remove another process's claim, as the strict claims section of docs/concepts.rst describes.

We referred to "the soft read/write marker break" three times in the break_lock_file docstring, 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 news in place of adding a changelog fragment.

@gaborbernat
gaborbernat force-pushed the docs-soft-marker-limits branch from 6f337ba to c9271f8 Compare October 1, 2026 21:25
@gaborbernat gaborbernat changed the title docs: clarify legacy soft marker write and recovery limits 馃摑 docs(util): fix write and stale-break claims Oct 1, 2026
@gaborbernat gaborbernat added the skip news Internal change; exempt from the news fragment check label 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 gaborbernat changed the title 馃摑 docs(util): fix write and stale-break claims 馃摑 docs(util): correct write and break guarantees Oct 1, 2026
@gaborbernat
gaborbernat force-pushed the docs-soft-marker-limits branch from c9271f8 to e0fa94c Compare October 1, 2026 21:32
@gaborbernat
gaborbernat merged commit 162060e into tox-dev:main Oct 1, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

skip news Internal change; exempt from the news fragment check

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants