filelock 4.2.0__tar.gz → 4.2.2__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {filelock-4.2.0 → filelock-4.2.2}/PKG-INFO +1 -1
- {filelock-4.2.0 → filelock-4.2.2}/docs/changelog.rst +117 -0
- {filelock-4.2.0 → filelock-4.2.2}/docs/concepts.rst +143 -44
- {filelock-4.2.0 → filelock-4.2.2}/docs/how-to.rst +59 -19
- {filelock-4.2.0 → filelock-4.2.2}/pyproject.toml +2 -0
- {filelock-4.2.0 → filelock-4.2.2}/src/filelock/_api.py +186 -60
- {filelock-4.2.0 → filelock-4.2.2}/src/filelock/_async.py +206 -75
- {filelock-4.2.0 → filelock-4.2.2}/src/filelock/_async_read_write.py +75 -34
- {filelock-4.2.0 → filelock-4.2.2}/src/filelock/_descriptor.py +1 -1
- {filelock-4.2.0 → filelock-4.2.2}/src/filelock/_identity.py +60 -12
- {filelock-4.2.0 → filelock-4.2.2}/src/filelock/_lease.py +42 -22
- {filelock-4.2.0 → filelock-4.2.2}/src/filelock/_marker.py +17 -6
- {filelock-4.2.0 → filelock-4.2.2}/src/filelock/_read_write.py +477 -140
- filelock-4.2.2/src/filelock/_soft.py +643 -0
- {filelock-4.2.0 → filelock-4.2.2}/src/filelock/_soft_rw/_async.py +88 -40
- {filelock-4.2.0 → filelock-4.2.2}/src/filelock/_soft_rw/_protocol.py +69 -33
- filelock-4.2.2/src/filelock/_soft_rw/_storage.py +276 -0
- {filelock-4.2.0 → filelock-4.2.2}/src/filelock/_soft_rw/_sync.py +118 -47
- {filelock-4.2.0 → filelock-4.2.2}/src/filelock/_strict.py +291 -109
- {filelock-4.2.0 → filelock-4.2.2}/src/filelock/_unix.py +80 -57
- filelock-4.2.2/src/filelock/_util.py +399 -0
- filelock-4.2.2/src/filelock/_windows.py +780 -0
- {filelock-4.2.0 → filelock-4.2.2}/src/filelock/asyncio.py +47 -26
- {filelock-4.2.0 → filelock-4.2.2}/src/filelock/version.py +2 -2
- {filelock-4.2.0 → filelock-4.2.2}/tasks/capabilities.py +29 -11
- {filelock-4.2.0 → filelock-4.2.2}/tasks/coverage_pragmas.py +2 -2
- {filelock-4.2.0 → filelock-4.2.2}/tests/capability_marks.py +11 -0
- filelock-4.2.2/tests/conftest.py +344 -0
- filelock-4.2.2/tests/pid_namespace_helpers.py +54 -0
- filelock-4.2.2/tests/process_helpers.py +73 -0
- {filelock-4.2.0 → filelock-4.2.2}/tests/read_write_helpers.py +26 -2
- {filelock-4.2.0 → filelock-4.2.2}/tests/soft_rw/test_soft_rw_async.py +326 -12
- {filelock-4.2.0 → filelock-4.2.2}/tests/soft_rw/test_soft_rw_protocol.py +164 -10
- {filelock-4.2.0 → filelock-4.2.2}/tests/soft_rw/test_soft_rw_storage.py +81 -7
- {filelock-4.2.0 → filelock-4.2.2}/tests/soft_rw/test_soft_rw_sync.py +397 -3
- {filelock-4.2.0 → filelock-4.2.2}/tests/test_async_filelock.py +152 -12
- {filelock-4.2.0 → filelock-4.2.2}/tests/test_async_filelock_acquire_cancellation.py +12 -4
- {filelock-4.2.0 → filelock-4.2.2}/tests/test_async_filelock_transition_admission.py +94 -1
- {filelock-4.2.0 → filelock-4.2.2}/tests/test_async_read_write.py +310 -1
- filelock-4.2.2/tests/test_async_read_write_cancel_wait.py +157 -0
- {filelock-4.2.0 → filelock-4.2.2}/tests/test_async_read_write_cancellation.py +53 -1
- filelock-4.2.2/tests/test_async_read_write_worker_ownership.py +111 -0
- {filelock-4.2.0 → filelock-4.2.2}/tests/test_async_transition_gate.py +85 -10
- {filelock-4.2.0 → filelock-4.2.2}/tests/test_default_mode.py +56 -0
- {filelock-4.2.0 → filelock-4.2.2}/tests/test_filelock.py +733 -67
- {filelock-4.2.0 → filelock-4.2.2}/tests/test_fork_coordination.py +128 -0
- filelock-4.2.2/tests/test_fork_registries.py +175 -0
- {filelock-4.2.0 → filelock-4.2.2}/tests/test_lock_expiry.py +36 -0
- {filelock-4.2.0 → filelock-4.2.2}/tests/test_marker_records.py +28 -3
- {filelock-4.2.0 → filelock-4.2.2}/tests/test_process_identity.py +131 -8
- {filelock-4.2.0 → filelock-4.2.2}/tests/test_read_write.py +604 -14
- {filelock-4.2.0 → filelock-4.2.2}/tests/test_read_write_fork.py +50 -36
- filelock-4.2.2/tests/test_read_write_private_link.py +415 -0
- {filelock-4.2.0 → filelock-4.2.2}/tests/test_read_write_unit.py +76 -6
- {filelock-4.2.0 → filelock-4.2.2}/tests/test_soft_lease.py +149 -1
- {filelock-4.2.0 → filelock-4.2.2}/tests/test_soft_stale.py +799 -23
- {filelock-4.2.0 → filelock-4.2.2}/tests/test_strict_soft_compat.py +22 -1
- {filelock-4.2.0 → filelock-4.2.2}/tests/test_strict_soft_failures.py +503 -122
- {filelock-4.2.0 → filelock-4.2.2}/tests/test_strict_soft_paths.py +0 -10
- {filelock-4.2.0 → filelock-4.2.2}/tests/test_unix_fallback.py +128 -1
- filelock-4.2.2/tests/test_util.py +677 -0
- {filelock-4.2.0 → filelock-4.2.2}/tox.toml +5 -0
- filelock-4.2.0/src/filelock/_soft.py +0 -388
- filelock-4.2.0/src/filelock/_soft_rw/_storage.py +0 -181
- filelock-4.2.0/src/filelock/_util.py +0 -153
- filelock-4.2.0/src/filelock/_windows.py +0 -365
- filelock-4.2.0/tests/conftest.py +0 -81
- filelock-4.2.0/tests/pid_namespace_helpers.py +0 -25
- filelock-4.2.0/tests/process_helpers.py +0 -32
- filelock-4.2.0/tests/test_fork_registries.py +0 -93
- filelock-4.2.0/tests/test_read_write_fd_fallback.py +0 -274
- filelock-4.2.0/tests/test_util.py +0 -314
- {filelock-4.2.0 → filelock-4.2.2}/.gitignore +0 -0
- {filelock-4.2.0 → filelock-4.2.2}/LICENSE +0 -0
- {filelock-4.2.0 → filelock-4.2.2}/README.md +0 -0
- {filelock-4.2.0 → filelock-4.2.2}/docs/_static/custom.css +0 -0
- {filelock-4.2.0 → filelock-4.2.2}/docs/api.rst +0 -0
- {filelock-4.2.0 → filelock-4.2.2}/docs/changelog/template.jinja2 +0 -0
- {filelock-4.2.0 → filelock-4.2.2}/docs/conf.py +0 -0
- {filelock-4.2.0 → filelock-4.2.2}/docs/example.gif +0 -0
- {filelock-4.2.0 → filelock-4.2.2}/docs/index.rst +0 -0
- {filelock-4.2.0 → filelock-4.2.2}/docs/license.rst +0 -0
- {filelock-4.2.0 → filelock-4.2.2}/docs/logo.svg +0 -0
- {filelock-4.2.0 → filelock-4.2.2}/docs/tutorials.rst +0 -0
- {filelock-4.2.0 → filelock-4.2.2}/src/filelock/__init__.py +0 -0
- {filelock-4.2.0 → filelock-4.2.2}/src/filelock/_error.py +0 -0
- {filelock-4.2.0 → filelock-4.2.2}/src/filelock/_soft_protocol.py +0 -0
- {filelock-4.2.0 → filelock-4.2.2}/src/filelock/_soft_rw/__init__.py +0 -0
- {filelock-4.2.0 → filelock-4.2.2}/src/filelock/py.typed +0 -0
- {filelock-4.2.0 → filelock-4.2.2}/tasks/benchmark.py +0 -0
- {filelock-4.2.0 → filelock-4.2.2}/tasks/capability/assert_fallback.py +0 -0
- {filelock-4.2.0 → filelock-4.2.2}/tasks/capability/sitecustomize.py +0 -0
- {filelock-4.2.0 → filelock-4.2.2}/tasks/deny_symlink.py +0 -0
- {filelock-4.2.0 → filelock-4.2.2}/tasks/termux/Dockerfile +0 -0
- {filelock-4.2.0 → filelock-4.2.2}/tasks/verify_filesystem.py +0 -0
- {filelock-4.2.0 → filelock-4.2.2}/tests/async_filelock_cancellation_helpers.py +0 -0
- {filelock-4.2.0 → filelock-4.2.2}/tests/fork_helpers.py +0 -0
- {filelock-4.2.0 → filelock-4.2.2}/tests/soft_rw/conftest.py +0 -0
- {filelock-4.2.0 → filelock-4.2.2}/tests/test_async_filelock_release_cancellation.py +0 -0
- {filelock-4.2.0 → filelock-4.2.2}/tests/test_async_filelock_rollback_agnostic.py +0 -0
- {filelock-4.2.0 → filelock-4.2.2}/tests/test_async_filelock_runner_shutdown.py +0 -0
- {filelock-4.2.0 → filelock-4.2.2}/tests/test_async_soft_contracts.py +0 -0
- {filelock-4.2.0 → filelock-4.2.2}/tests/test_error.py +0 -0
- {filelock-4.2.0 → filelock-4.2.2}/tests/test_fork_backends.py +0 -0
- {filelock-4.2.0 → filelock-4.2.2}/tests/test_fork_ownership.py +0 -0
- {filelock-4.2.0 → filelock-4.2.2}/tests/test_host_name_grammar.py +0 -0
- {filelock-4.2.0 → filelock-4.2.2}/tests/test_lazy_import.py +0 -0
- {filelock-4.2.0 → filelock-4.2.2}/tests/test_lifetime_validation.py +0 -0
- {filelock-4.2.0 → filelock-4.2.2}/tests/test_soft_lifetime_warning.py +0 -0
- {filelock-4.2.0 → filelock-4.2.2}/tests/test_strict_soft.py +0 -0
- {filelock-4.2.0 → filelock-4.2.2}/tests/test_strict_soft_races.py +0 -0
- {filelock-4.2.0 → filelock-4.2.2}/tests/test_strict_soft_recovery.py +0 -0
- {filelock-4.2.0 → filelock-4.2.2}/tests/test_strict_soft_stress.py +0 -0
- {filelock-4.2.0 → filelock-4.2.2}/tests/test_subclass_options.py +0 -0
- {filelock-4.2.0 → filelock-4.2.2}/tests/test_virtualenv.py +0 -0
|
@@ -6,6 +6,123 @@
|
|
|
6
6
|
|
|
7
7
|
.. towncrier release notes start
|
|
8
8
|
|
|
9
|
+
*******************
|
|
10
|
+
4.2.2 (2026-10-18)
|
|
11
|
+
*******************
|
|
12
|
+
|
|
13
|
+
- Fix a lock on a relative path that stayed held after a later ``with lock:`` ended, when an earlier ``acquire()`` had
|
|
14
|
+
failed because the working directory no longer exists. That call still raises :class:`FileNotFoundError`, and it now
|
|
15
|
+
leaves the lock's hold count unchanged. :pr:`856`
|
|
16
|
+
|
|
17
|
+
*******************
|
|
18
|
+
4.2.1 (2026-10-17)
|
|
19
|
+
*******************
|
|
20
|
+
|
|
21
|
+
- On a singleton wrapper, :meth:`AsyncReadWriteLock.close() <filelock.AsyncReadWriteLock.close>` and
|
|
22
|
+
:meth:`AsyncSoftReadWriteLock.close() <filelock.AsyncSoftReadWriteLock.close>` end only the holds that tasks acquired
|
|
23
|
+
through that wrapper. A reader that arrives during ``close()`` gets the closed error instead of joining the ending hold.
|
|
24
|
+
After synchronous code closes or force-releases the shared lock, the wrappers refuse to admit readers into the ended
|
|
25
|
+
hold, and ``close()`` on such a wrapper returns.
|
|
26
|
+
Closing one wrapper no longer ends a task's nested hold taken through another wrapper on the same path. :pr:`832`
|
|
27
|
+
- :class:`~filelock.ReadWriteLock` locks again after a ``release()`` that an exception from a signal handler interrupted.
|
|
28
|
+
The async read-write wrappers stop admitting readers into such a level. The async read-write locks forget a hold whose
|
|
29
|
+
backend release failed after the backend let go, and they free the memory of each acquire that times out or is canceled.
|
|
30
|
+
:class:`~filelock.AsyncFileLock` returns from ``release()`` after a few hundred acquires gave up behind a waiting one. An exception from a signal handler delivered while an :class:`~filelock.AsyncFileLock` call joins
|
|
31
|
+
its queue no longer blocks every later call on that lock. :pr:`833`
|
|
32
|
+
- Fix :class:`~filelock.ReadWriteLock` acting on ``-journal``, ``-wal`` or ``-shm`` files another process puts beside its
|
|
33
|
+
database: a write could land in another file, a reader could get in beside a writer, and an acquire could fail. SQLite
|
|
34
|
+
now opens the database by name only in a directory no other account can write, and through a private hard link
|
|
35
|
+
elsewhere. On Windows the directory's access control list decides. Where hard links are unavailable, keep the database
|
|
36
|
+
in a directory other accounts cannot write, such as one under ``%LOCALAPPDATA%``. The lock removes link directories
|
|
37
|
+
through a checked descriptor rather than by name, reads a link directory's name only when the locking account owns it,
|
|
38
|
+
and leaves alone a directory with other content renamed onto a link directory's name. A database whose schema takes more
|
|
39
|
+
than a few kilobytes to load raises :class:`ValueError` instead of running past the acquire timeout. :pr:`834`
|
|
40
|
+
- Fix five bugs in opening the lock file. :class:`~filelock.UnixFileLock` no longer truncates a file it did not create,
|
|
41
|
+
such as one renamed to the lock path, and no longer applies ``mode`` to it. An ``on_acquired`` hook that writes holder
|
|
42
|
+
metadata now truncates the file itself. A lease (Linux) or an oplock (Windows) on the lock file or a soft lock's marker
|
|
43
|
+
no longer holds ``acquire()`` past its ``timeout`` or ``blocking=False``, and an oplock no longer holds ``release()``;
|
|
44
|
+
:class:`~filelock.ReadWriteLock` on Windows waits for its ``timeout`` and raises :class:`~filelock.Timeout`. On Windows,
|
|
45
|
+
a ``mode`` without group and other bits, such as ``0o600``, now creates the lock file with an owner-only permission
|
|
46
|
+
list; the :class:`~filelock.ReadWriteLock` database gets the same. The soft locks' writability check no longer follows a
|
|
47
|
+
symlink swapped in at the lock path. On a filesystem without ``flock``, a contender from another account now waits on a
|
|
48
|
+
marker it cannot write instead of raising ``PermissionError``. :pr:`835`
|
|
49
|
+
- Fix :class:`~filelock.SoftFileLock`, :class:`~filelock.MarkerSoftFileLock` and :class:`~filelock.SoftFileLease` removing
|
|
50
|
+
a live holder's marker in three cases: the holder and the contender run in Linux time namespaces with different boottime
|
|
51
|
+
offsets; only one of them can read the boot id; a process other than the owner rewrote the marker. Soft markers no
|
|
52
|
+
longer carry group or other write bits. A process name containing a carriage return or another line separator no longer
|
|
53
|
+
makes the stale check raise :class:`ValueError`. When ``/proc/self/ns/time`` exists but cannot be read, the stale check
|
|
54
|
+
no longer compares start times and keeps the marker. :pr:`836`
|
|
55
|
+
- The async read-write locks record their hold under a task owner, so synchronous code on the executor thread that took
|
|
56
|
+
the hold can no longer re-enter or release it. :class:`~filelock.AsyncSoftReadWriteLock` gives back one level on
|
|
57
|
+
release, so synchronous readers of a shared singleton keep theirs. :class:`~filelock.SoftReadWriteLock` tracks read
|
|
58
|
+
levels per thread: ``release()`` from a thread that holds none raises :class:`RuntimeError`. After its heartbeat
|
|
59
|
+
recorded a lost hold, it refuses new acquires until that hold is released. :pr:`838`
|
|
60
|
+
- :class:`~filelock.StrictSoftFileLock` creates ``<path>.filelock`` and its ``claims`` directory with the lock's ``mode``
|
|
61
|
+
and sets the sticky bit (a directory flag that lets only a file's owner remove it) on both. On the next acquisition it
|
|
62
|
+
narrows a directory it owns that an earlier release created wider; it leaves a directory of another account as it is,
|
|
63
|
+
so remove such leftovers by hand. It reaches ``claims`` through a descriptor opened without following symlinks; on
|
|
64
|
+
Windows it holds both directories open and refuses a junction (a directory that points at another directory). Under a
|
|
65
|
+
sticky parent such as ``/tmp`` it refuses a coordination directory of another account, as
|
|
66
|
+
:class:`~filelock.SoftReadWriteLock` does for ``<path>.rw``. One read grace now covers a whole claim scan, a failed
|
|
67
|
+
claim cleanup no longer leaves the sentinel descriptor open, and a non-regular node at a sentinel private-record name
|
|
68
|
+
raises :class:`~filelock.SoftFileLockProtocolError`. On Windows, contenders read claims without blocking their owner's
|
|
69
|
+
unlink. :pr:`839`
|
|
70
|
+
- Fix a lock reporting a hold the OS had dropped after a signal handler raised during
|
|
71
|
+
:meth:`~filelock.BaseFileLock.acquire` or :meth:`~filelock.BaseFileLock.release`. A release that a signal handler cuts
|
|
72
|
+
short after it has started now completes before the error propagates. A handler that acquires the lock its own thread is
|
|
73
|
+
releasing now gets :class:`RuntimeError` instead of a hold that stays held. The singleton cache no longer hands out an
|
|
74
|
+
``is_singleton=True`` lock or a :class:`~filelock.ReadWriteLock` whose finalizer is running, which released the new
|
|
75
|
+
holder's lock. A signal during ``os.fork()`` no longer leaves the other threads blocked in their next lock call, and a
|
|
76
|
+
fork from another thread no longer waits for a :class:`~filelock.ReadWriteLock` acquire on a busy database. :pr:`840`
|
|
77
|
+
- Fix a lock on a relative path locking a file in the directory the process changed to while the lock waited, and leaving
|
|
78
|
+
its marker behind on release after such a change. The path resolved when an acquisition starts stays in use until
|
|
79
|
+
the hold ends. An ``is_singleton=True`` lookup no longer returns a cached lock whose relative path now resolves to
|
|
80
|
+
another file; a held lock still matches the file it holds. A rename of the lock's directory during a hold no longer
|
|
81
|
+
leaves the marker behind or reports a false lease compromise, and a waiter no longer creates a second lock file in a
|
|
82
|
+
directory that was renamed away. :pr:`841`
|
|
83
|
+
- :class:`~filelock.SoftReadWriteLock` reaches its records through descriptors of ``<path>.rw`` and ``gen`` or ``holders``
|
|
84
|
+
opened without following symlinks. On Windows it holds those directories open and refuses a junction (a directory that
|
|
85
|
+
points at another directory). A tree swapped in after an earlier acquire therefore cannot redirect them. Its heartbeat
|
|
86
|
+
rewrites a holder record only when the name still leads to the file it created, and does not block on a FIFO (a named
|
|
87
|
+
pipe). A heartbeat that finds ``<path>.rw`` replaced by a symlink or junction reports the hold lost instead of ending
|
|
88
|
+
the heartbeat thread. A live lock object repeats the ownership check whenever the tree it opens is not the one it
|
|
89
|
+
prepared. :pr:`842`
|
|
90
|
+
- Fix :class:`~filelock.SoftFileLock`, :class:`~filelock.MarkerSoftFileLock` and :class:`~filelock.SoftFileLease` removing
|
|
91
|
+
or displacing a live holder's marker in five cases. ext4 gave a freed inode number to the next marker. A stalled
|
|
92
|
+
:class:`~filelock.FileLock` removed its ``ENOSYS`` placeholder after a peer replaced it. A failed acquire cleaned up
|
|
93
|
+
after a successor took the path. A stale break left the lock path empty while it checked the marker it had moved. A
|
|
94
|
+
``lifetime`` break judged a marker by a reused inode number. On Linux and macOS a stale marker now changes hands in one
|
|
95
|
+
atomic exchange. On other platforms without one, except Windows, including NFS and SMB, the marker stays in place and
|
|
96
|
+
waits for ``timeout`` or ``break_lock()``. Restoring a marker no longer follows a symlink found under the break name. A
|
|
97
|
+
holder that releases while a peer's exchange has its marker aside leaves a record no lock parses, so the put-back lands
|
|
98
|
+
a marker that ages out. A lease heartbeat that finds another file at the lock path once, while a peer's break has its
|
|
99
|
+
marker aside, waits for the next refresh before it reports a compromise. A contender that finds a dead breaker's marker
|
|
100
|
+
puts back the marker that breaker left under its break name. A marker is the breaker's own only when it names the
|
|
101
|
+
breaker's process on this host; the same process number on another host is a holder. A contender takes a stranded marker
|
|
102
|
+
under a name of its own before it puts the marker back, so two contenders no longer reverse each other's exchange and
|
|
103
|
+
remove the live holder's marker. A claim left behind by a failed put-back is retried on the next poll. :pr:`843`
|
|
104
|
+
- Canceling an :class:`~filelock.AsyncReadWriteLock` or :class:`~filelock.AsyncSoftReadWriteLock` acquire that waits for
|
|
105
|
+
another process now stops the wait and raises the cancellation. It used to wait until that process released, or raise
|
|
106
|
+
:class:`~filelock.Timeout`. A ``thread_local=True`` :class:`~filelock.AsyncFileLock` that threads with their own event
|
|
107
|
+
loops share no longer deadlocks when one thread waits for the lock while another holds it. :pr:`844`
|
|
108
|
+
- :class:`~filelock.SoftReadWriteLock` refuses a commit that lands a whole retention window behind the log, so two
|
|
109
|
+
committers stalled at adjacent generations can no longer admit a second writer. Its stale check samples the clock before
|
|
110
|
+
it reads a holder record, so a pause between the two no longer counts as time the record stayed unchanged. :pr:`845`
|
|
111
|
+
- Fix a :class:`~filelock.SoftFileLock` contender evicting an empty marker after two seconds while its owner held the
|
|
112
|
+
lock. The owner is a ``SoftFileLock`` before 3.22, which writes nothing into its marker, or a current one still writing
|
|
113
|
+
its record. An empty marker now reads as held, and ``timeout``, ``lifetime`` or ``break_lock()`` clears it. A contender
|
|
114
|
+
that finds an empty marker a dead breaker left aside puts it back instead of removing it. :pr:`846`
|
|
115
|
+
- Fix :class:`~filelock.ReadWriteLock` on Windows acting on ``-journal`` and ``-wal`` files another account places beside
|
|
116
|
+
its database: an acquire could fail with :class:`sqlite3.OperationalError`, or SQLite could replay the journal and
|
|
117
|
+
delete the file it names. The lock now reads the database directory's access control list. Where an account other than
|
|
118
|
+
the locking account, ``SYSTEM`` and ``Administrators`` can add or remove names, SQLite opens a hard link inside a
|
|
119
|
+
directory only those accounts can write. A filesystem without hard links raises :class:`OSError`. :pr:`854`
|
|
120
|
+
- Fix ``SoftReadWriteLock`` subclasses sharing singleton instances with the base class or sibling subclasses.
|
|
121
|
+
Each concrete class now keeps its own cache and construction guard, including after fork, while preserving
|
|
122
|
+
cooperative class-definition keywords. :pr:`855`
|
|
123
|
+
- GraalPy is now tested weekly instead of on every change: GraalPy 25.4.4 can freeze the test suite, which made its job
|
|
124
|
+
fail on unrelated changes. :pr:`849`
|
|
125
|
+
|
|
9
126
|
*******************
|
|
10
127
|
4.2.0 (2026-10-14)
|
|
11
128
|
*******************
|
|
@@ -169,6 +169,15 @@ Every strict participant needs filelock 3.30.0 or newer. Legacy clients configur
|
|
|
169
169
|
``break_lock()``, and code that deletes lock files can remove the sentinel; mixing them with strict clients voids mutual
|
|
170
170
|
exclusion.
|
|
171
171
|
|
|
172
|
+
The lock creates ``<path>.filelock`` and its ``claims`` directory with its ``mode``, plus search permission where the
|
|
173
|
+
mode grants read, so ``mode=0o600`` gives ``0o700``. It sets the sticky bit (a directory flag that lets only a file's
|
|
174
|
+
owner remove it) on both, so only the account that published a claim can remove it. On each acquisition it
|
|
175
|
+
narrows a directory it owns to the mode, which covers one an earlier release created wider. Under a sticky parent such
|
|
176
|
+
as ``/tmp``, acquisition raises :class:`SoftFileLockProtocolError <filelock.SoftFileLockProtocolError>` when
|
|
177
|
+
``<path>.filelock`` belongs to an account that owns neither the lock nor the parent. Where the platform supports
|
|
178
|
+
``dir_fd``, the lock reaches ``claims`` through a descriptor of ``<path>.filelock`` opened without following symlinks.
|
|
179
|
+
A symlink swapped in for either directory then fails the operation instead of redirecting it.
|
|
180
|
+
|
|
172
181
|
Strict claims require coherent directory reads and atomic no-replace hard links. The class reports a protocol error
|
|
173
182
|
when the filesystem reports that it cannot publish hard links. NFS and SMB remain outside this guarantee until their
|
|
174
183
|
mount and server combination passes the protocol tests. Linux documents the hard-link lock pattern in `open(2)
|
|
@@ -219,6 +228,13 @@ Losing a private name makes the publisher retry; it never converts an unpublishe
|
|
|
219
228
|
stable pathname across releases, construct the lock with ``preserve_lock_file=True`` (see :ref:`how-to:Keep the lock
|
|
220
229
|
file on release`).
|
|
221
230
|
|
|
231
|
+
An oplock (opportunistic lock: a notice sent to a process holding a handle before another process opens the file,
|
|
232
|
+
which the opener waits on until the holder answers) on the lock file does not hold an acquire past its ``timeout``.
|
|
233
|
+
The open reports contention, and the retry loop keeps the deadline. :class:`~filelock.ReadWriteLock` waits for its
|
|
234
|
+
``timeout`` on an oplocked database and then raises :class:`~filelock.Timeout`. Release deletes the lock file
|
|
235
|
+
through a handle that does not wait for an oplock holder either, so a holder that never answers leaves the file in
|
|
236
|
+
place.
|
|
237
|
+
|
|
222
238
|
**Unix and macOS**
|
|
223
239
|
Uses the :class:`UnixFileLock <filelock.UnixFileLock>` class, backed by the kernel's ``fcntl.flock`` interface. The
|
|
224
240
|
interface is common on Unix systems but is not specified by POSIX. The lock is exclusive and enforced by the kernel.
|
|
@@ -230,10 +246,12 @@ Losing a private name makes the publisher retry; it never converts an unpublishe
|
|
|
230
246
|
exclusion; remove the file only after the complete lock protocol has stopped using it.
|
|
231
247
|
|
|
232
248
|
Filesystems without ``flock``: when ``flock`` fails with ``ENOSYS``, the lock switches to :class:`SoftFileLock
|
|
233
|
-
<filelock.SoftFileLock>` and emits a warning, unless constructed with ``fallback_to_soft=False``. Before switching
|
|
234
|
-
removes the empty file only if this acquire created it.
|
|
235
|
-
|
|
236
|
-
|
|
249
|
+
<filelock.SoftFileLock>` and emits a warning, unless constructed with ``fallback_to_soft=False``. Before switching
|
|
250
|
+
it removes the empty file only if this acquire created it. It does so while still holding the file open, with the
|
|
251
|
+
exchange a stale break uses, so a peer's marker that replaced it is put back rather than deleted. A file that
|
|
252
|
+
already existed may be another process's soft marker, so it stays and the soft lock waits on it. An empty file there
|
|
253
|
+
reads as a holder that recorded nothing, as a release before 3.22 writes. A leftover one therefore waits for
|
|
254
|
+
``timeout``, ``lifetime`` or ``break_lock()``.
|
|
237
255
|
|
|
238
256
|
**Other platforms without fcntl**
|
|
239
257
|
Falls back to :class:`SoftFileLock <filelock.SoftFileLock>` and emits a warning. The lock is not enforced by the OS,
|
|
@@ -430,17 +448,34 @@ How filelock mitigates this:
|
|
|
430
448
|
The defense differs by platform:
|
|
431
449
|
|
|
432
450
|
- On Unix, filelock opens lock files with ``O_NOFOLLOW``, so a symlink planted at the lock path makes the open fail
|
|
433
|
-
instead of reaching its target.
|
|
451
|
+
instead of reaching its target. ``O_NOFOLLOW`` does not catch a hard link (a second name for the same file) or a file
|
|
452
|
+
renamed to the lock path, and such a file is indistinguishable from a lock file. :class:`UnixFileLock
|
|
453
|
+
<filelock.UnixFileLock>` therefore locks a file it did not create as found, without truncating it or changing its
|
|
454
|
+
mode.
|
|
434
455
|
- Windows has no ``O_NOFOLLOW``. :class:`WindowsFileLock <filelock.WindowsFileLock>` opens the file without following
|
|
435
456
|
reparse points and rejects a symlink or junction by inspecting the handle it locks, so a swap between check and use
|
|
436
457
|
cannot redirect it. Only the last path component is guarded; the lock directory must not be writable by untrusted
|
|
437
458
|
users.
|
|
438
459
|
- :class:`SoftFileLock <filelock.SoftFileLock>` creates its marker with ``O_CREAT | O_EXCL``, which fails on any
|
|
439
460
|
existing name. Before reading a marker it classifies the path with ``lstat`` and treats anything other than a regular
|
|
440
|
-
file as malformed, then checks the opened handle again with ``fstat``.
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
461
|
+
file as malformed, then checks the opened handle again with ``fstat``. On Windows it reads and breaks markers through
|
|
462
|
+
handles that do not wait for an oplock holder to answer, so an oplock on a marker ends as contention and the
|
|
463
|
+
``timeout`` holds.
|
|
464
|
+
- :class:`StrictSoftFileLock <filelock.StrictSoftFileLock>` opens ``<path>.filelock`` with ``O_NOFOLLOW`` and reaches
|
|
465
|
+
``claims`` relative to that descriptor on platforms that support ``dir_fd``. A symlink swapped in for either
|
|
466
|
+
directory after the check cannot redirect where claims are created, listed or removed.
|
|
467
|
+
- :class:`SoftReadWriteLock <filelock.SoftReadWriteLock>` opens ``<path>.rw`` and then ``gen`` or ``holders`` without
|
|
468
|
+
following symlinks for every record operation on platforms that support ``dir_fd``. A tree swapped in after an
|
|
469
|
+
earlier acquire cannot redirect its writes. It rewrites a holder record only when the name still leads to the file it
|
|
470
|
+
created and that file has no second name, and it opens the record without blocking. It leaves alone a hard link (a
|
|
471
|
+
second name for the same file) or a FIFO (a named pipe) renamed over the record.
|
|
472
|
+
|
|
473
|
+
:class:`ReadWriteLock <filelock.ReadWriteLock>` refuses a symlink at its database path. In a directory that processes of
|
|
474
|
+
other accounts can write, it opens SQLite through a hard link (a second name for the same file) in a directory only the
|
|
475
|
+
locking account can read, so a link or journal file another process puts beside the database cannot point the lock at
|
|
476
|
+
another file. On Windows the directory counts as writable by other accounts unless its owner and every entry of its
|
|
477
|
+
access control list (ACL) that allows adding or removing names belong to the locking account, ``SYSTEM`` or
|
|
478
|
+
``Administrators``.
|
|
444
479
|
|
|
445
480
|
***************************************
|
|
446
481
|
What filelock doesn't protect against
|
|
@@ -509,6 +544,17 @@ because that co-tenant owns the files and can bypass the protocol. Treat every s
|
|
|
509
544
|
follow the protocol. Where that assumption does not hold, a file lock is the wrong tool; use an OS mechanism that enforces
|
|
510
545
|
access, such as a privilege boundary or a broker process.
|
|
511
546
|
|
|
547
|
+
The directory boundary
|
|
548
|
+
======================
|
|
549
|
+
|
|
550
|
+
Every protection filelock gives against processes of other accounts holds only while none of them can replace the
|
|
551
|
+
lock's directory or any of its ancestors. Each ancestor must belong to the account the lock runs as or to root, and must
|
|
552
|
+
either not be writable by others or carry the sticky bit. A process that can rename entries in a non-sticky ancestor
|
|
553
|
+
can move the lock file or protocol directory aside, even one it cannot read, and put its own in its place. Holders that
|
|
554
|
+
reached the old one keep using it while new contenders use the replacement, so two of them hold the lock at once and
|
|
555
|
+
neither learns of it. No check inside the lock can rule that out, because the owner of such a directory controls every name
|
|
556
|
+
in it. Keep locks in a directory that only the lock's users can write, or in a sticky one such as ``/tmp``.
|
|
557
|
+
|
|
512
558
|
Native locks are advisory
|
|
513
559
|
==========================
|
|
514
560
|
|
|
@@ -594,12 +640,20 @@ cannot expire a live claim. In exchange a contender that first sees a long-aband
|
|
|
594
640
|
Malformed and legacy markers
|
|
595
641
|
============================
|
|
596
642
|
|
|
597
|
-
A soft lock treats a record it cannot parse as malformed, not as a holder.
|
|
598
|
-
<filelock.SoftFileLock>`
|
|
599
|
-
|
|
600
|
-
|
|
601
|
-
|
|
602
|
-
|
|
643
|
+
A soft lock treats a record it cannot parse as malformed, not as a holder. An empty marker is the exception: it is the
|
|
644
|
+
whole marker of a :class:`SoftFileLock <filelock.SoftFileLock>` before 3.22, held for as long as its owner runs, and
|
|
645
|
+
also what a current acquirer shows before it writes its record. A contender therefore waits on it like on any live
|
|
646
|
+
holder. A plain :class:`SoftFileLock <filelock.SoftFileLock>` self-heals any other malformed marker once it has watched
|
|
647
|
+
it stay unchanged for a short grace window on its own monotonic clock, which absorbs the brief gap between creating a
|
|
648
|
+
marker and writing its record.
|
|
649
|
+
|
|
650
|
+
It tells markers apart by modification time, inode number and change time (the time the kernel last changed the file's
|
|
651
|
+
metadata). An owner can set a file's modification time, and ext4 hands a freed inode number to the next file, but no
|
|
652
|
+
process can set the change time. A new marker therefore never inherits the time spent watching an old one.
|
|
653
|
+
|
|
654
|
+
A strict lock never age-breaks, so it fails closed on an unreadable claim. A marker written by an older filelock stays
|
|
655
|
+
readable: the process start token is an integer, so a 3.29 reader parses a newer marker as well-formed and stays
|
|
656
|
+
conservative rather than evicting a live holder.
|
|
603
657
|
|
|
604
658
|
Filesystem support matrix
|
|
605
659
|
=========================
|
|
@@ -679,24 +733,54 @@ Every platform records the holder's PID, hostname, and a process start token in
|
|
|
679
733
|
only when the recorded owner is provably gone. A PID that no longer exists is gone; a live PID whose start token differs
|
|
680
734
|
is a recycled PID, so the process that wrote the marker is gone; a live PID whose token still matches, a token that
|
|
681
735
|
cannot be read, and a marker from another host all read as held. The start token is ``kill(pid, 0)`` plus the
|
|
682
|
-
``starttime`` from ``/proc/<pid>/stat`` folded with the boot id on Linux, ``sysctl`` process start time on macOS, and
|
|
683
|
-
``GetProcessTimes`` creation time on Windows.
|
|
684
|
-
|
|
685
|
-
|
|
686
|
-
|
|
687
|
-
|
|
688
|
-
|
|
689
|
-
|
|
690
|
-
|
|
691
|
-
|
|
692
|
-
|
|
693
|
-
|
|
694
|
-
|
|
695
|
-
the
|
|
696
|
-
|
|
697
|
-
|
|
698
|
-
|
|
699
|
-
|
|
736
|
+
``starttime`` from ``/proc/<pid>/stat`` folded with the boot id on Linux, ``sysctl`` process start time on macOS, and
|
|
737
|
+
the ``GetProcessTimes`` creation time on Windows.
|
|
738
|
+
|
|
739
|
+
A malformed or unparsable record follows a separate rule: a waiter may remove it once it has seen it unchanged for two
|
|
740
|
+
seconds, so a half-written marker never wedges acquisition. An empty marker is the exception and always reads as held.
|
|
741
|
+
This is the rule PostgreSQL, Qt ``QLockFile``, and Mercurial converge on: break a stale lock only on proof of death.
|
|
742
|
+
|
|
743
|
+
Two Linux processes do not always read the same token for one task. Since Linux 5.6 the kernel adds the reader's
|
|
744
|
+
boottime offset (the shift a time namespace applies to the boot clock) to ``starttime``. A process in a time namespace
|
|
745
|
+
with such an offset therefore records no start token and reads none. It falls back to the PID alone, so a recycled PID
|
|
746
|
+
keeps a dead owner's marker until ``timeout``, ``lifetime`` or ``break_lock()``. A time namespace without an offset, as
|
|
747
|
+
container runtimes create, keeps the token. A process that cannot read ``/proc/sys/kernel/random/boot_id`` (systemd's
|
|
748
|
+
``ProcSubset=pid`` hides it) records ``starttime`` without the boot id. A contender then compares ``starttime`` alone
|
|
749
|
+
whenever either side lacks the boot id.
|
|
750
|
+
|
|
751
|
+
A contender never leaves the lock path empty while it breaks a marker. Right before breaking it reads the marker's inode
|
|
752
|
+
(the kernel's identity for a file, independent of its name) and modification time again. If they moved since the stale
|
|
753
|
+
check, it leaves the marker alone, the way Mercurial re-reads a lock under its break lock before removing it. On Linux
|
|
754
|
+
(``renameat2``) and macOS (``renamex_np``) it then writes a complete marker of its own under a private
|
|
755
|
+
``<lock>.break.*`` name and exchanges the two names in one step. A contender that polls meanwhile finds a marker and
|
|
756
|
+
waits.
|
|
757
|
+
|
|
758
|
+
If the file it took is the one judged stale, it removes that file and holds the lock from then on. A peer that
|
|
759
|
+
exchanges after that moves the holder's marker aside only while it checks what it took, and puts it back. A holder that
|
|
760
|
+
releases while its marker is aside leaves a record no lock parses, so the put-back lands a marker that ages out.
|
|
761
|
+
Otherwise a peer recreated the marker, and a second exchange puts the live marker back before its own is removed.
|
|
762
|
+
|
|
763
|
+
The private name is ``<lock>.break.<pid>.<token>``: the breaker's PID, then 32 random hex digits. A breaker killed
|
|
764
|
+
between its exchange and the put-back leaves its own marker at the lock path and a live holder's marker under that name.
|
|
765
|
+
A contender that finds the breaker's marker dead first looks in the lock's directory for names that start with
|
|
766
|
+
``<lock>.break.<pid>.``, where ``<pid>`` is the dead breaker's. It first renames the record to
|
|
767
|
+
``<lock>.restore.<pid>.<token>`` with its own PID, so only one of several contenders acts on it; a record whose
|
|
768
|
+
recoverer died there is claimable again, and a claim a failed put-back left in the same process is retried on the next
|
|
769
|
+
poll. It then exchanges back a marker whose owner is alive or cannot be proven dead, and removes one whose owner is
|
|
770
|
+
dead. Where the filesystem refuses that exchange, the lock counts as held until ``timeout`` or ``break_lock()``. The
|
|
771
|
+
placeholder a break writes while it works carries the same PID, so a contender that evicts a placeholder a killed
|
|
772
|
+
process left finds the same names.
|
|
773
|
+
|
|
774
|
+
The contender holds the judged marker open from before it reads the record until the break ends. ext4 gives a freed
|
|
775
|
+
inode number to the next file created, so a successor's marker could otherwise carry the number of the marker judged
|
|
776
|
+
stale.
|
|
777
|
+
|
|
778
|
+
Windows has no such exchange, but it refuses to rename a marker its live holder keeps open. There the contender renames
|
|
779
|
+
the marker aside, checks it, and links back a marker it took by mistake; ``link`` never replaces a name. Anywhere else
|
|
780
|
+
without an exchange, including NFS and SMB, which refuse it, a contender does not move a marker at all, because the path
|
|
781
|
+
would stand empty beside a possibly live holder. The marker then counts as held until ``timeout`` or ``break_lock()``.
|
|
782
|
+
The ``lifetime`` and :class:`SoftFileLease <filelock.SoftFileLease>` expiry breaks follow the same rules, and a failed
|
|
783
|
+
acquire removes its own marker by the same exchange before it closes it.
|
|
700
784
|
|
|
701
785
|
A PID means something only inside its PID namespace, and two containers in one pod share the hostname and the boot id
|
|
702
786
|
without sharing one. On Linux the recorded hostname therefore names the namespace too, as ``<host>?pidns-<inode>`` with
|
|
@@ -708,14 +792,16 @@ start token instead: a 3.30 reader compares the whole token and would read any n
|
|
|
708
792
|
A release before the namespace was recorded wrote the bare hostname from inside a container too, so a contender in the
|
|
709
793
|
host's namespace reads such a marker from a container that shares the hostname (host networking) as local, where its PID
|
|
710
794
|
names another process or none. Before it calls that owner dead it looks for a task in another namespace whose innermost
|
|
711
|
-
PID (``NSpid`` in ``/proc/<pid>/status``) and start token match the record, since ``starttime`` and the boot id
|
|
712
|
-
|
|
713
|
-
|
|
714
|
-
|
|
715
|
-
|
|
716
|
-
|
|
717
|
-
|
|
718
|
-
|
|
795
|
+
PID (``NSpid`` in ``/proc/<pid>/status``) and start token match the record, since ``starttime`` and the boot id read the
|
|
796
|
+
same in every PID namespace, and keeps the marker if one exists. From a time namespace with a boottime offset it matches
|
|
797
|
+
the innermost PID alone.
|
|
798
|
+
|
|
799
|
+
Three limits remain. A marker without a start token, a kernel before 4.1 without ``NSpid``, or a ``/proc`` this process
|
|
800
|
+
cannot list leaves the check nothing to find. Where ``/proc/self/ns/pid`` cannot be read, the bare hostname is all that
|
|
801
|
+
separates namespaces. And a contender never reclaims a marker from another namespace: a container that crashes and is
|
|
802
|
+
replaced comes back in a new namespace. A :class:`~filelock.Timeout` names such a holder. Containers that can crash
|
|
803
|
+
while holding a soft lock should use :class:`SoftFileLease <filelock.SoftFileLease>`, set ``lifetime``, or call
|
|
804
|
+
``break_lock()`` at entrypoint once nothing else can hold the path.
|
|
719
805
|
|
|
720
806
|
Why is ReadWriteLock backed by SQLite?
|
|
721
807
|
======================================
|
|
@@ -944,8 +1030,11 @@ inherited ``with lock.read_lock():`` block can unwind in the child without raisi
|
|
|
944
1030
|
fresh ``SoftReadWriteLock(path)`` before it can acquire again. This matches PyMongo's connection-pool semantics.
|
|
945
1031
|
|
|
946
1032
|
**Trust boundary.** The class coordinates cooperating processes. Directory ownership, ACLs, and ``0o600`` / ``0o700``
|
|
947
|
-
permissions can exclude another UID.
|
|
948
|
-
|
|
1033
|
+
permissions can exclude another UID. Under a sticky parent such as ``/tmp``, acquisition raises :class:`RuntimeError`
|
|
1034
|
+
when ``<path>.rw``, ``gen`` or ``holders`` belongs to an account that owns neither the lock nor the parent. The refusal
|
|
1035
|
+
also applies to a lock object that used an earlier tree: it repeats the check whenever a directory it opens is not the
|
|
1036
|
+
one it prepared. A process with the same effective UID can alter the records. A filesystem that delays a rewrite's
|
|
1037
|
+
visibility past ``stale_threshold`` can also trigger expiry while a holder remains active.
|
|
949
1038
|
|
|
950
1039
|
****************************
|
|
951
1040
|
File permissions and mode
|
|
@@ -957,7 +1046,17 @@ inheritance so the lock file gets the directory's default permissions rather tha
|
|
|
957
1046
|
|
|
958
1047
|
When you pass an explicit ``mode`` value (e.g., ``mode=0o644``), filelock creates the file with it. On Unix,
|
|
959
1048
|
:class:`UnixFileLock <filelock.UnixFileLock>` and :class:`SoftFileLock <filelock.SoftFileLock>` then apply it with
|
|
960
|
-
``fchmod``, so the umask cannot narrow it. This overrides any default ACLs on the directory.
|
|
1049
|
+
``fchmod``, so the umask cannot narrow it. This overrides any default ACLs on the directory. A Unix lock file that
|
|
1050
|
+
already exists keeps the mode it has. A soft lock's marker never gets the group or other write bits, whatever the
|
|
1051
|
+
``mode`` or umask. Contenders only read and rename it, and they act on the record its owner wrote.
|
|
1052
|
+
|
|
1053
|
+
Windows has no mode bits. A new file inherits the ACL (access control list, the Windows permission list) of its
|
|
1054
|
+
directory. :class:`WindowsFileLock <filelock.WindowsFileLock>` honors the one ``mode`` that has a Windows counterpart: a
|
|
1055
|
+
``mode`` without group and other bits, such as ``0o600``, creates the lock file with an ACL that grants access to its
|
|
1056
|
+
owner, ``SYSTEM`` and ``Administrators`` only, the ACL ``os.mkdir(mode=0o700)`` applies. The
|
|
1057
|
+
:class:`~filelock.ReadWriteLock` database, always ``0o600``, gets the same ACL. A file that already exists keeps its own
|
|
1058
|
+
ACL. Every other ``mode`` inherits the directory's ACL, as do the files of the soft locks, which ``os.open`` creates;
|
|
1059
|
+
restrict the directory's ACL to keep other accounts out.
|
|
961
1060
|
|
|
962
1061
|
An explicit ``mode`` must be an :class:`int` within ``0o000``-``0o777`` that grants the owner read and write;
|
|
963
1062
|
construction raises :class:`TypeError` for another type and :class:`ValueError` otherwise. A lock reopens, reads, and
|
|
@@ -42,6 +42,8 @@ Two more constraints worth designing around:
|
|
|
42
42
|
- **All contenders must agree on the path.** A lock is a rendezvous on one pathname. Resolve symlinks and relative
|
|
43
43
|
paths the same way everywhere, or two processes will politely lock different files. Bind-mounted containers make this
|
|
44
44
|
easy to get wrong: the same file, two paths, no exclusion.
|
|
45
|
+
filelock resolves a relative path when an acquisition starts and keeps that path until the hold ends. Do not rename
|
|
46
|
+
the lock's directory while a lock in it is held or waited on: a waiter then fails with :class:`FileNotFoundError`.
|
|
45
47
|
- **Create the resource's directory when using a separate lock tree.** filelock creates the lock file's parent
|
|
46
48
|
directories automatically, but it does not create directories for the resource being protected.
|
|
47
49
|
|
|
@@ -432,12 +434,38 @@ Parameters are frozen when the singleton is first created. Requesting the same p
|
|
|
432
434
|
|
|
433
435
|
When you have many readers and occasional writers, use :class:`ReadWriteLock <filelock.ReadWriteLock>` to allow readers
|
|
434
436
|
to proceed concurrently. ``ReadWriteLock`` is backed by SQLite; a ``.db`` extension is a convention rather than a
|
|
435
|
-
requirement. Use a local filesystem the active SQLite VFS supports and a database file of its own.
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
|
|
437
|
+
requirement. Use a local filesystem the active SQLite VFS supports and a database file of its own. Two kinds of file
|
|
438
|
+
raise :class:`ValueError`: a database in WAL mode (SQLite's write-ahead log, which never blocks readers behind a
|
|
439
|
+
writer), and a database whose schema takes more than a few kilobytes to load, because the acquire timeout does not
|
|
440
|
+
bound that load.
|
|
441
|
+
|
|
442
|
+
On POSIX, SQLite opens the database by name. It also uses the names ``<database>-journal``, ``<database>-wal`` and
|
|
443
|
+
``<database>-shm`` beside it, so a file placed under one of those names changes what SQLite does. filelock therefore
|
|
444
|
+
names the database directly only when no process of another account can create names in its directory: the directory
|
|
445
|
+
belongs to the locking account or root and is not writable by its group or by others. In any other directory, filelock
|
|
446
|
+
opens SQLite through a hard link (a second name for the same file) inside a ``.filelock-*`` directory that only the
|
|
447
|
+
locking account can read. That directory must be writable by the locking account, and the filesystem must support hard
|
|
448
|
+
links; when the link cannot be made, the lock raises :class:`OSError`.
|
|
449
|
+
|
|
450
|
+
Both routes assume that no process of another account can replace the database directory or any directory above it.
|
|
451
|
+
That holds when every directory above belongs to the locking account or root and is either not writable by others or
|
|
452
|
+
has the sticky bit (a directory flag that lets only a file's owner rename or remove it).
|
|
453
|
+
|
|
454
|
+
A process that can rename an entry in a directory above owns every name below it, and can put a replacement at the
|
|
455
|
+
database path between the lock's checks. filelock compares the name with the file it checked before it runs any SQL statement, and raises
|
|
456
|
+
:class:`OSError` instead of reporting the lock held, and leaves the replacement's files as they were, except that
|
|
457
|
+
SQLite's open creates an empty ``lock.db`` there when the name is missing, following a symlink at that name. A swap that lands after that
|
|
458
|
+
comparison and before SQLite's first statement still makes SQLite look up ``-journal`` and ``-wal`` under the
|
|
459
|
+
replacement: it deletes both, and beside a non-empty lock database it first replays the journal into that database and
|
|
460
|
+
unlinks the file the journal names.
|
|
461
|
+
|
|
462
|
+
On Windows the lock makes the same choice from the directory's access control list (ACL). It connects by the database
|
|
463
|
+
name only when the directory's owner and every entry that allows adding files, adding subdirectories or deleting entries
|
|
464
|
+
name the locking account, ``SYSTEM`` or ``Administrators``. Otherwise it links the database into a directory created
|
|
465
|
+
with an ACL that grants only those accounts, and SQLite opens the link. The filesystem must support hard links, or the
|
|
466
|
+
lock raises :class:`OSError`. Where it does not, as on FAT or some network shares, keep the database in a directory
|
|
467
|
+
other accounts cannot create files in. The per-user temporary directory and ``%LOCALAPPDATA%`` qualify,
|
|
468
|
+
``C:\Windows\Temp`` and ``C:\Users\Public`` do not.
|
|
441
469
|
|
|
442
470
|
.. code-block:: python
|
|
443
471
|
|
|
@@ -628,9 +656,9 @@ expired holder can resume:
|
|
|
628
656
|
# A store that rejects a lower generation than the highest it accepted refuses an evicted holder that resumes.
|
|
629
657
|
store.write(payload, fence=rw.generation)
|
|
630
658
|
|
|
631
|
-
As with ``ReadWriteLock``, ``release()`` of a write lock from another thread raises ``RuntimeError
|
|
632
|
-
|
|
633
|
-
thread.
|
|
659
|
+
As with ``ReadWriteLock``, ``release()`` of a write lock from another thread raises ``RuntimeError``, and so does
|
|
660
|
+
``release()`` from a thread that holds no level of a shared read lock. ``on_compromise`` runs on the hold's own heartbeat
|
|
661
|
+
thread, so it may release, and ``release(force=True)`` and ``close()`` work from any thread.
|
|
634
662
|
|
|
635
663
|
``timeout`` and ``blocking`` set instance-wide defaults that each acquisition inherits. Passing ``None`` per call means
|
|
636
664
|
"use the instance default", which is not the same as ``-1``:
|
|
@@ -745,6 +773,10 @@ time of the call rather than at construction:
|
|
|
745
773
|
finally:
|
|
746
774
|
await rw.close() # shuts down the executor it created
|
|
747
775
|
|
|
776
|
+
With the default ``is_singleton=True`` every wrapper on a path shares one lock, so ``close()`` ends only the holds of
|
|
777
|
+
tasks that acquired through that wrapper. Tasks holding through another wrapper, and synchronous ``ReadWriteLock`` users
|
|
778
|
+
of the same path, keep their locks.
|
|
779
|
+
|
|
748
780
|
Low-level ``acquire_read``/``acquire_write``/``release`` methods are also available:
|
|
749
781
|
|
|
750
782
|
.. code-block:: python
|
|
@@ -803,11 +835,13 @@ a reused PID can also keep a dead owner's marker in place.
|
|
|
803
835
|
Every platform stores a process start token in the marker to guard against PID recycling: Linux uses the
|
|
804
836
|
``/proc/<pid>/stat`` start time folded with the boot id, macOS reads it through ``sysctl``, and Windows uses the
|
|
805
837
|
``GetProcessTimes`` creation time. Malformed records follow a different rule: a waiter may evict them once it has seen
|
|
806
|
-
them unchanged for two seconds.
|
|
838
|
+
them unchanged for two seconds. An empty marker, which is all a ``SoftFileLock`` before 3.22 writes, is never evicted
|
|
839
|
+
this way; remove a leftover one with ``break_lock()``.
|
|
807
840
|
That recovery path is not fail closed.
|
|
808
841
|
|
|
809
|
-
A contender
|
|
810
|
-
|
|
842
|
+
A contender breaks a stale marker without the lock path ever standing empty. Where it cannot (NFS, SMB and platforms
|
|
843
|
+
without an atomic exchange, other than Windows) it leaves the marker in place; see :ref:`concepts:How does stale lock
|
|
844
|
+
detection work across platforms?` for the details.
|
|
811
845
|
|
|
812
846
|
********************************
|
|
813
847
|
Use fail-closed soft locks
|
|
@@ -844,13 +878,14 @@ A soft-lock owner's marker at ``work.lock`` (from ``SoftFileLock``, ``MarkerSoft
|
|
|
844
878
|
strict acquisition like any holder, without appearing in ``lock.claims``; :attr:`lock_path_occupant
|
|
845
879
|
<filelock.StrictSoftFileLock.lock_path_occupant>` describes it, with its PID and host when the marker records them. A
|
|
846
880
|
file strict cannot read blocks the same way, because Windows refuses to read a marker its holder keeps open. A file it
|
|
847
|
-
reads but cannot parse, such as the empty marker filelock before 3.22 wrote or
|
|
881
|
+
reads but cannot parse, such as the empty marker filelock before 3.22 wrote or an empty ``UnixFileLock`` lock file,
|
|
848
882
|
blocks while it changes and raises :class:`SoftFileLockProtocolError <filelock.SoftFileLockProtocolError>` once it stays
|
|
849
|
-
unchanged for two seconds, the grace a soft contender waits before evicting
|
|
850
|
-
|
|
851
|
-
|
|
852
|
-
|
|
853
|
-
|
|
883
|
+
unchanged for two seconds, the grace a soft contender waits before evicting a malformed marker other than an empty one.
|
|
884
|
+
|
|
885
|
+
A marker whose owner on this host has exited raises the same error naming that owner, and a directory, symlink, or other
|
|
886
|
+
node no lock writes raises it after half a second. Strict mode never removes what it found. A crashed owner on another
|
|
887
|
+
host, or one that left no PID, cannot be told apart from a live one, so its marker blocks until an operator who has
|
|
888
|
+
confirmed that owner is gone deletes ``work.lock``.
|
|
854
889
|
|
|
855
890
|
A crash can leave an intent, a held claim, or both claims for one token. Strict mode treats each claim as live because
|
|
856
891
|
PID and clock checks cannot prove that another host or a recycled process has stopped using the resource. Inspect the
|
|
@@ -1310,6 +1345,10 @@ thread returns without doing anything, and the interrupted release finishes the
|
|
|
1310
1345
|
while the interrupted code is still acquiring that lock raises :class:`RuntimeError`: the interrupted acquire cannot go
|
|
1311
1346
|
on until the handler returns.
|
|
1312
1347
|
|
|
1348
|
+
A ``release()`` that a handler interrupts after it has started finishes releasing before the handler's exception
|
|
1349
|
+
propagates, so the ``with`` block above never leaves the lock held. Only a handler that fires at the very entry of
|
|
1350
|
+
``release()`` leaves the hold for the next call.
|
|
1351
|
+
|
|
1313
1352
|
*******************************
|
|
1314
1353
|
Check your own lock state
|
|
1315
1354
|
*******************************
|
|
@@ -1452,7 +1491,8 @@ write, seek, truncate, or set metadata through ``os`` on it, but must not close,
|
|
|
1452
1491
|
descriptor. A recursive acquire does not call it again. If the callback raises, filelock releases the lock and
|
|
1453
1492
|
re-raises.
|
|
1454
1493
|
|
|
1455
|
-
A common use is
|
|
1494
|
+
A common use is writing holder metadata into the lock file. filelock does not empty an existing lock file, so the hook
|
|
1495
|
+
truncates what an earlier holder wrote:
|
|
1456
1496
|
|
|
1457
1497
|
.. code-block:: python
|
|
1458
1498
|
|
|
@@ -266,6 +266,8 @@ standalone.lazy-exclude-modules = [
|
|
|
266
266
|
# installs its sqlite audit hook and fork handler at import, and must fail at import without sqlite3 so the package
|
|
267
267
|
# __getattr__ resolves ReadWriteLock and AsyncReadWriteLock to None
|
|
268
268
|
"filelock._read_write",
|
|
269
|
+
# a marker released from a finalizer at interpreter exit unlinks through it, and a first import then fails
|
|
270
|
+
"filelock._windows",
|
|
269
271
|
# registers its atexit cleanup at import
|
|
270
272
|
"filelock._soft_rw._sync",
|
|
271
273
|
# a Python built without it must fail at import, as for filelock._read_write
|