Skip to content

feat: file_lock / FileLock next to atomic_write (#163) - #164

Merged
thorwhalen merged 3 commits into
masterfrom
feat/file-lock
Oct 26, 2026
Merged

thorwhalen merged 3 commits into
masterfrom
feat/file-lock

Conversation

@thorwhalen

@thorwhalen thorwhalen commented Oct 26, 2026 •

Copy link
Copy Markdown
Member

Closes #163. Adds dol.file_lock(path) (one-off context manager, yields whether the lock is held) and dol.FileLock (reusable, keeps its handle) in dol/atomic.py. Additive; no new dependency.

Behaviour (from xdol#23): fork-safe (pid check, reopen; thread lock renewed in the child), Windows polls LK_NBLCK instead of LK_LOCK, read-only lock file falls back to a read-only open, unsupported filesystems / unopenable lock file run the body with held=False. Threads of one process exclude each other too.

Not included: the optional "appender that follows an atomically replaced file" (stays in xdol; follow-up issue).

Tests: multi-process, threads, fork inheritance, read-only lock file, release on exception, doctests.

Adversarial review (Opus, two rounds)

Round 1 found: a forked child leaving the with released the parent's lock; the multiprocess test was vacuous (O_APPEND is atomic anyway); sidecar="" swapped the locked inode under atomic_write; open failures were swallowed; same-thread nesting deadlocked; unclosed handles. Round 2 found the fork hook's fresh thread lock made the child's __exit__ raise, finalizer pile-up, close() inside the block deadlocking.
Fixed: child __exit__ is a no-op; multiprocess test is now a read-modify-write counter; sidecar must be non-empty; only read-only/permission cases degrade to held=False, anything else raises; reentry and in-block close() raise; one finalizer; defaults hoisted to constants. Not changed: NFS per-process fcntl semantics (two locks in one process don't exclude on NFS) is inherent to flock emulation. Verdict after fixes: merge.

@thorwhalen
thorwhalen merged commit 8d6cced into master Oct 26, 2026
12 checks passed
@thorwhalen
thorwhalen deleted the feat/file-lock branch October 26, 2026 20:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

file_lock: a fork-safe, cross-platform advisory lock next to atomic_write

1 participant