Initial commit

This commit is contained in:
Alex committed 2026-11-02 22:54:14 +08:00
commit 57fc3525eb
7311 files changed
+1291398

No files matched your search

@@ -0,0 +1,793 @@
"""Cross-process and cross-host reader/writer lock over a generation log of immutable snapshots."""
from __future__ import annotations
__lazy_modules__ = [
"filelock._error",
"filelock._lease",
"filelock._soft_rw._protocol",
"filelock._soft_rw._storage",
"math",
]
import atexit
import os
import threading
import time
from contextlib import contextmanager, suppress
from dataclasses import dataclass
from math import isfinite
from typing import TYPE_CHECKING, ClassVar, Final
from weakref import WeakValueDictionary
from filelock._api import (
AcquireReturnProxy,
_acquire_thread_lock,
_canonical,
_check_timeout_max,
_ensure_current_process,
_register_fork_class,
_register_fork_object,
_resolve_read_write_timeout,
_seconds,
_timeout_behavior,
)
from filelock._error import Timeout
from filelock._lease import LeaseCompromise
from filelock._soft_rw._protocol import GenerationLog, Ledger, Mode, Participant
from filelock._soft_rw._storage import OsFiles
if TYPE_CHECKING:
from collections.abc import Callable, Generator
from filelock._lease import CompromiseReason
_ALL_INSTANCES: Final[WeakValueDictionary[int, SoftReadWriteLock]] = WeakValueDictionary()
_ALL_INSTANCES_LOCK: threading.Lock = threading.Lock()
class _SoftRWMeta(type):
_instances: WeakValueDictionary[str, SoftReadWriteLock]
_instances_lock: threading.RLock
_instances_under_construction: set[str]
def __call__( # ruff:ignore[too-many-arguments] # forwards the public constructor's documented parameters
cls,
lock_file: str | os.PathLike[str],
timeout: float = -1,
*,
blocking: bool = True,
is_singleton: bool = True,
heartbeat_interval: float = 30.0,
stale_threshold: float | None = None,
poll_interval: float = 0.25,
on_compromise: Callable[[LeaseCompromise], None] | None = None,
) -> SoftReadWriteLock:
_ensure_current_process()
timeout = _seconds("timeout", timeout)
# Passed through only when set, so a subclass that declares its own constructor without it keeps working.
extra = {} if on_compromise is None else {"on_compromise": on_compromise}
if not is_singleton:
return super().__call__(
lock_file,
timeout,
blocking=blocking,
is_singleton=is_singleton,
heartbeat_interval=heartbeat_interval,
stale_threshold=stale_threshold,
poll_interval=poll_interval,
**extra,
)
# Keyed like the log root, so one instance never spans two logs.
normalized = _canonical(lock_file)
with cls._instances_lock:
instance = cls._instances.get(normalized)
if instance is None:
if normalized in cls._instances_under_construction:
msg = f"Singleton lock construction is already active for {lock_file!s}"
raise RuntimeError(msg)
construction_pid = os.getpid()
construction_registry = cls._instances_under_construction
construction_registry.add(normalized)
try:
instance = super().__call__(
lock_file,
timeout,
blocking=blocking,
is_singleton=is_singleton,
heartbeat_interval=heartbeat_interval,
stale_threshold=stale_threshold,
poll_interval=poll_interval,
**extra,
)
finally:
construction_registry.discard(normalized)
if os.getpid() != construction_pid: # pragma: needs fork
msg = "Lock construction cannot continue after fork; construct a new lock in the child"
raise RuntimeError(msg)
cls._instances[normalized] = instance
elif (
_timeout_behavior(instance.timeout, any_negative=False)
!= _timeout_behavior(timeout, any_negative=False)
or instance.blocking != blocking
):
msg = (
f"Singleton lock created with timeout={instance.timeout}, blocking={instance.blocking},"
f" cannot be changed to timeout={timeout}, blocking={blocking}"
)
raise ValueError(msg)
elif on_compromise is not None and instance._on_compromise != on_compromise: # ruff: ignore[private-member-access] # the metaclass owns the singleton it compares
# A tuning difference keeps the first caller's values; a different loss callback is a different safety
# contract, and returning the cached instance would silently drop it.
msg = f"Singleton lock created with a different on_compromise callback for {lock_file!s}"
raise ValueError(msg)
else:
_validate_intervals(heartbeat_interval, stale_threshold, poll_interval)
return instance
class SoftReadWriteLock(metaclass=_SoftRWMeta):
"""
Cross-process and cross-host reader/writer lock for shared filesystems.
Use this class instead of :class:`~filelock.ReadWriteLock` when the lock file lives on a network filesystem (NFS,
Lustre, HPC cluster shared storage). ``ReadWriteLock`` is backed by SQLite and cannot run on NFS because SQLite's
``fcntl`` locking is unreliable there.
The lock's state is a log of immutable snapshots under ``foo.lock.rw/gen/<N>``, each naming the writer and the
readers holding the lock at generation ``N``. Every acquire, release, and eviction publishes the next snapshot with
one atomic no-replace hard link, so no transition can be left half done by a crash on any host. Each participant
also keeps ``foo.lock.rw/holders/<token>``, a record whose nonce a daemon heartbeat thread rewrites every
``heartbeat_interval`` seconds. A contender evicts a member whose record has not changed for ``stale_threshold``
seconds of the contender's own monotonic clock; no clock is ever compared across hosts, so skew between hosts or
against the file server cannot make a live holder look dead.
Writer acquire is writer-preferring: a writer enters the snapshot as soon as no live writer is named, which blocks
any new reader, then waits for the named readers to leave. Writer starvation is impossible.
An expired holder is not fenced by the lock: a process paused past ``stale_threshold`` resumes believing it holds
the lock until its next heartbeat reports the loss through ``on_compromise``. :attr:`generation` is a monotonic
fencing token for the protected resource: a store that rejects writes carrying a lower generation than the highest
it has accepted refuses such a holder.
Reentrancy, upgrade/downgrade rules, thread pinning, and singleton caching by canonical path match
:class:`~filelock.ReadWriteLock`.
Forking invalidates the inherited instance in the child so the child cannot double-own the lock with its parent;
``release()`` on that instance is a no-op, and the child must construct a new instance if it needs a lock.
Trust boundary: protects against same-UID non-cooperating processes (one host or cross-host) and same-host
different-UID users via ``0o600`` / ``0o700`` permissions. Does not protect against root compromise or multi-tenant
mounts where hostile co-tenants share the UID.
:param lock_file: path to the lock file; the protocol directory lives next to it as ``<lock_file>.rw``
:param timeout: maximum wait time in seconds; ``-1`` means block indefinitely
:param blocking: if ``False``, raise :class:`~filelock.Timeout` immediately on contention
:param is_singleton: if ``True``, reuse existing instances for the same canonical path
:param heartbeat_interval: seconds between heartbeat refreshes; default 30 s
:param stale_threshold: seconds a holder record may stay unchanged before a contender evicts it; defaults to
``3 * heartbeat_interval``, matching etcd's ``LeaseKeepAlive`` convention
:param poll_interval: seconds between acquire retries under contention; default 0.25 s
:param on_compromise: called from the heartbeat thread with a :class:`~filelock.LeaseCompromise` when the hold is
lost: a peer evicted it, or refreshes failed for long enough that a peer could have
.. versionadded:: 3.27.0
.. versionchanged:: 3.33.0
The on-disk protocol is a generation log; earlier releases cannot share a lock path with this one.
"""
_instances: WeakValueDictionary[str, SoftReadWriteLock] = WeakValueDictionary()
_instances_lock = threading.RLock()
_instances_under_construction: ClassVar[set[str]] = set()
def __init_subclass__(cls, **kwargs: object) -> None:
"""Give each lock subclass its own singleton registry and lock."""
super().__init_subclass__(**kwargs)
cls._instances = WeakValueDictionary()
cls._instances_lock = threading.RLock()
cls._instances_under_construction = set()
_register_fork_class(cls)
def __init__( # ruff:ignore[too-many-arguments] # public constructor: one parameter per documented lock option
self,
lock_file: str | os.PathLike[str],
timeout: float = -1,
*,
blocking: bool = True,
is_singleton: bool = True, # ruff:ignore[unused-method-argument] # consumed by _SoftRWMeta.__call__
heartbeat_interval: float = 30.0,
stale_threshold: float | None = None,
poll_interval: float = 0.25,
on_compromise: Callable[[LeaseCompromise], None] | None = None,
) -> None:
self._creator_pid = os.getpid()
heartbeat_interval, stale_threshold, poll_interval = _validate_intervals(
heartbeat_interval, stale_threshold, poll_interval
)
self.lock_file: str = os.fspath(lock_file)
self.timeout: float = timeout
self.blocking: bool = blocking
self.heartbeat_interval: float = heartbeat_interval
self.stale_threshold: float = stale_threshold
self.poll_interval: float = poll_interval
# Resolved once: a relative lock path must keep naming the same log after the process changes directory. The
# final component stays unresolved, as in 4.0.12, so every release shares one log on a symlinked lock path.
self._root = f"{_canonical(self.lock_file)}.rw"
self._files = OsFiles(self.lock_file)
self._ledger = Ledger(time.monotonic)
self._log = GenerationLog(self._files, self.lock_file, self._root)
self._on_compromise = on_compromise
self._locks = _Locks(internal=threading.Lock(), transaction=threading.Lock())
self._hold: _Hold | None = None
self._compromise: LeaseCompromise | None = None
self._closed: bool = False
with _ALL_INSTANCES_LOCK:
_ALL_INSTANCES[id(self)] = self
_register_fork_object(self)
@classmethod
def _reset_class_after_fork(cls) -> None: # pragma: forked child
global _ALL_INSTANCES_LOCK # ruff:ignore[global-statement] # rebinds the module lock to a fresh one in the fork child
_ALL_INSTANCES_LOCK = threading.Lock()
cls._instances = WeakValueDictionary()
cls._instances_lock = threading.RLock()
cls._instances_under_construction = set()
@property
def generation(self) -> int | None:
"""
The generation at which the current hold was granted, or ``None`` when no lock is held.
Generations are monotonic across all participants and hosts, so this is a fencing token: pass it to the
protected resource and have the resource reject any operation carrying a lower generation than the highest it
has accepted. That refuses a holder that paused past ``stale_threshold``, was evicted, and resumed. Removing the
``<lock_file>.rw`` directory starts a new log whose generations begin again at 1.
.. versionadded:: 3.33.0
"""
with self._locks.internal:
return None if self._hold is None else self._hold.participant.generation
@property
def compromise(self) -> LeaseCompromise | None:
"""
How the current hold was lost, or ``None`` while it stands.
Set by the heartbeat thread once a peer has evicted this holder or refreshes have failed for long enough that a
peer could have. The holder should stop using the protected resource when it is set. Until the lost hold is
released, acquiring on this instance raises :class:`RuntimeError` instead of joining it.
.. versionadded:: 3.33.0
"""
with self._locks.internal:
return self._compromise
@contextmanager
def read_lock(self, timeout: float | None = None, *, blocking: bool | None = None) -> Generator[None]:
"""
Context manager that acquires and releases a shared read lock.
Falls back to instance defaults for *timeout* and *blocking* when ``None``.
:param timeout: maximum wait time in seconds, or ``None`` to use the instance default
:param blocking: if ``False``, raise :class:`~filelock.Timeout` immediately; ``None`` uses the instance default
:raises RuntimeError: if a write lock is already held on this instance
:raises Timeout: if the lock cannot be acquired within *timeout* seconds
:raises TypeError: if *timeout* is a :class:`bool` or not a real number
:raises ValueError: if a blocking call gets a ``nan`` *timeout* or a negative one other than ``-1``
"""
self.acquire_read(timeout, blocking=blocking)
try:
yield
finally:
self.release()
@contextmanager
def write_lock(self, timeout: float | None = None, *, blocking: bool | None = None) -> Generator[None]:
"""
Context manager that acquires and releases an exclusive write lock.
Falls back to instance defaults for *timeout* and *blocking* when ``None``.
:param timeout: maximum wait time in seconds, or ``None`` to use the instance default
:param blocking: if ``False``, raise :class:`~filelock.Timeout` immediately; ``None`` uses the instance default
:raises RuntimeError: if a read lock is already held, or a write lock is held by a different thread
:raises Timeout: if the lock cannot be acquired within *timeout* seconds
:raises TypeError: if *timeout* is a :class:`bool` or not a real number
:raises ValueError: if a blocking call gets a ``nan`` *timeout* or a negative one other than ``-1``
"""
self.acquire_write(timeout, blocking=blocking)
try:
yield
finally:
self.release()
def acquire_read(self, timeout: float | None = None, *, blocking: bool | None = None) -> AcquireReturnProxy:
"""
Acquire a shared read lock.
If this instance already holds a read lock, the lock level is incremented (reentrant). Attempting to acquire a
read lock while holding a write lock raises :class:`RuntimeError` (downgrade not allowed). On the 0→1
transition the reader publishes its holder record, enters the next snapshot once no live writer is named, and
starts a daemon heartbeat thread that rewrites the record's nonce every ``heartbeat_interval`` seconds so peers
on other hosts do not evict it.
:param timeout: maximum wait time in seconds, or ``None`` to use the instance default; ``-1`` means block
indefinitely
:param blocking: if ``False``, raise :class:`~filelock.Timeout` immediately when the lock is unavailable;
``None`` uses the instance default
:returns: a proxy that can be used as a context manager to release the lock
:raises RuntimeError: if a write lock is already held on this instance, if this instance was invalidated by
:func:`os.fork`, or if :meth:`close` was called
:raises Timeout: if the lock cannot be acquired within *timeout* seconds
:raises TypeError: if *timeout* is a :class:`bool` or not a real number
:raises ValueError: if a blocking call gets a ``nan`` *timeout* or a negative one other than ``-1``
:raises SoftFileLockProtocolError: if a snapshot cannot be read without risking overlap, or the filesystem
refuses the no-replace hard links the protocol commits with
"""
return self._acquire("read", timeout, blocking=blocking)
def acquire_write(self, timeout: float | None = None, *, blocking: bool | None = None) -> AcquireReturnProxy:
"""
Acquire an exclusive write lock.
If this instance already holds a write lock from the same thread, the lock level is incremented (reentrant).
Attempting to acquire a write lock while holding a read lock raises :class:`RuntimeError` (upgrade not
allowed). Write locks are pinned to the acquiring thread: a different thread trying to re-enter also raises
:class:`RuntimeError`.
A writer enters the next snapshot as its writer as soon as no live writer is named, which blocks every new
reader on every host, then waits for the readers that snapshot names to leave. Writer starvation is impossible:
new readers see the named writer and wait behind it.
:param timeout: maximum wait time in seconds, or ``None`` to use the instance default; ``-1`` means block
indefinitely
:param blocking: if ``False``, raise :class:`~filelock.Timeout` immediately when the lock is unavailable;
``None`` uses the instance default
:returns: a proxy that can be used as a context manager to release the lock
:raises RuntimeError: if a read lock is already held, if a write lock is held by a different thread, if this
instance was invalidated by :func:`os.fork`, or if :meth:`close` was called
:raises Timeout: if the lock cannot be acquired within *timeout* seconds
:raises TypeError: if *timeout* is a :class:`bool` or not a real number
:raises ValueError: if a blocking call gets a ``nan`` *timeout* or a negative one other than ``-1``
:raises SoftFileLockProtocolError: if a snapshot cannot be read without risking overlap, or the filesystem
refuses the no-replace hard links the protocol commits with
"""
return self._acquire("write", timeout, blocking=blocking)
@classmethod
def get_lock(
cls,
lock_file: str | os.PathLike[str],
timeout: float = -1,
*,
blocking: bool = True,
) -> SoftReadWriteLock:
"""
Return the singleton :class:`SoftReadWriteLock` for *lock_file*.
:param lock_file: path to the lock file; the protocol directory lives next to it as ``<lock_file>.rw``
:param timeout: maximum wait time in seconds; ``-1`` means block indefinitely
:param blocking: if ``False``, raise :class:`~filelock.Timeout` immediately when the lock is unavailable
:returns: the singleton lock instance
:raises ValueError: if an instance already exists for this path with different *timeout* or *blocking* values
"""
return cls(lock_file, timeout, blocking=blocking)
def close(self) -> None:
"""
Release any held lock and mark the instance closed.
Idempotent. After calling this method the instance can no longer acquire locks — subsequent acquires raise
:class:`RuntimeError`, and so does an acquire another thread is still waiting in, which gives up its claim
instead of taking the lock. A fork-invalidated instance is closed without raising.
"""
if self._creator_pid != os.getpid(): # pragma: forked child
return
# Closed first, under the lock an acquire publishes its hold under: an acquire still waiting then sees the flag
# and leaves instead of publishing, and one that published before it is released below.
with self._locks.internal:
self._closed = True
self.release(force=True)
def release(self, *, force: bool = False) -> None:
"""
Release one level of the current lock.
When the lock level reaches zero the heartbeat thread is stopped, the participant is committed out of the next
snapshot, and its holder record is removed. On a fork-invalidated instance (that is, the child of a
:func:`os.fork` call made while the parent held a lock) this method is a no-op so inherited ``with`` blocks can
unwind cleanly in the child.
:param force: if ``True``, release the lock completely regardless of the current lock level
:raises RuntimeError: if no lock is currently held and *force* is ``False``, or if the calling thread holds no
level of the current lock and *force* is ``False``
"""
if self._creator_pid != os.getpid(): # pragma: forked child
return
self._release(threading.get_ident(), force=force)
def _acquire_level_of(
self, holder: int, mode: Mode, timeout: float, *, blocking: bool, cancel_check: Callable[[], bool]
) -> AcquireReturnProxy:
# Records the level under *holder* instead of the calling thread: an async wrapper's executor thread does not
# identify the tasks it holds for. Gives up with Timeout once *cancel_check* is true.
return self._acquire(mode, timeout, blocking=blocking, holder=holder, cancel_check=cancel_check)
def _release_level_of(self, holder: int) -> None:
self._release(holder, force=False)
def _holds_level_of(self, holder: int) -> bool:
# Read without the internal lock: an async wrapper asks from its event loop, which must not wait out a release
# running on another thread.
return (hold := self._hold) is not None and (holder == hold.write_thread_id or holder in hold.read_depths)
def _release(self, thread_id: int, *, force: bool) -> None:
with self._locks.internal:
hold = self._hold
if hold is None:
if force:
return
msg = f"Cannot release a lock on {self.lock_file} (lock id: {id(self)}) that is not held"
raise RuntimeError(msg)
if force:
hold.level = 0
else:
self._raise_if_not_holder(hold, thread_id)
hold.leave_one_level(thread_id)
if hold.level > 0:
return
self._hold = None
# Stop the heartbeat before leaving, so a late tick cannot re-read a snapshot this participant just left and
# report an eviction that was its own release. on_compromise runs on that thread and may be what called here,
# in which case there is nothing to join.
hold.heartbeat_stop.set()
try:
if hold.heartbeat_thread is not threading.current_thread():
hold.heartbeat_thread.join(timeout=min(self.heartbeat_interval + 1.0, threading.TIMEOUT_MAX))
finally:
# The hold is already gone from this instance, so a join that raises must not strand its record too.
hold.participant.leave()
def _raise_if_not_holder(self, hold: _Hold, thread_id: int) -> None:
# The hold's own heartbeat thread may release it, since on_compromise runs there.
if thread_id == hold.heartbeat_thread.ident:
return
# Another thread's release would leave the generation log under the holder and let a peer in.
if hold.mode == "write" and thread_id != hold.write_thread_id:
msg = (
f"Cannot release write lock on {self.lock_file} (lock id: {id(self)}) "
f"from thread {thread_id} while it is held by thread {hold.write_thread_id}"
)
raise RuntimeError(msg)
# Readers share one participant, so a thread that holds no read level would end another's hold.
if hold.mode == "read" and thread_id not in hold.read_depths:
msg = (
f"Cannot release read lock on {self.lock_file} (lock id: {id(self)}) "
f"from thread {thread_id}, which does not hold it"
)
raise RuntimeError(msg)
def _acquire(
self,
mode: Mode,
timeout: float | None,
*,
blocking: bool | None,
holder: int | None = None,
cancel_check: Callable[[], bool] | None = None,
) -> AcquireReturnProxy:
if self._creator_pid != os.getpid(): # pragma: forked child
msg = f"SoftReadWriteLock on {self.lock_file} was invalidated by fork(); construct a new instance"
raise RuntimeError(msg)
timeout = self.timeout if timeout is None else timeout
blocking = self.blocking if blocking is None else blocking
holder = threading.get_ident() if holder is None else holder
with self._locks.internal:
if self._closed:
raise self._closed_error()
timeout = _resolve_read_write_timeout(timeout, blocking=blocking)
if self._hold is not None:
return self._validate_reentrant(mode, holder)
deadline = None if timeout == -1 else time.perf_counter() + timeout
if not _acquire_thread_lock(
self._locks.transaction,
blocking=blocking,
timeout=timeout,
poll_interval=self.poll_interval,
cancel_check=cancel_check,
):
raise Timeout(self.lock_file) from None
try:
return self._do_acquire_inner(mode, deadline, holder, blocking=blocking, cancel_check=cancel_check)
finally:
self._locks.transaction.release()
def _closed_error(self) -> RuntimeError:
return RuntimeError(f"SoftReadWriteLock on {self.lock_file} has been closed")
def _do_acquire_inner(
self,
mode: Mode,
deadline: float | None,
holder: int,
*,
blocking: bool,
cancel_check: Callable[[], bool] | None,
) -> AcquireReturnProxy:
with self._locks.internal:
if self._hold is not None:
return self._validate_reentrant(mode, holder)
participant = Participant(
self._files,
self._root,
mode,
stale_threshold=self.stale_threshold,
clock=time.monotonic,
ledger=self._ledger,
log=self._log,
)
participant.publish()
try:
self._wait_for(participant.advance, deadline=deadline, blocking=blocking, cancel_check=cancel_check)
except BaseException:
# A contender that gives up must not stay named in the snapshot: a writer left there would block every
# reader until a peer waits out the stale threshold. Its own token is all leave() touches, so it cannot
# undo a peer's claim.
with suppress(OSError):
participant.leave()
raise
stop_event = threading.Event()
hold = _Hold(
level=1,
mode=mode,
write_thread_id=holder if mode == "write" else None,
read_depths={holder: 1} if mode == "read" else {},
participant=participant,
heartbeat_thread=_HeartbeatThread(
refresh=lambda: self._refresh(participant, hold),
interval=self.heartbeat_interval,
stop_event=stop_event,
name=f"filelock-heartbeat-{id(self):x}",
),
heartbeat_stop=stop_event,
last_refresh=time.monotonic(),
)
# Publish the hold and start its heartbeat under one internal-lock section, so a concurrent release() never
# observes a hold whose thread has not started and joins it. If the OS refuses the thread, clear the hold and
# leave: left in place, a peer evicts the unrefreshed record and acquires while this instance still believes it
# holds the lock. A close() that landed while this acquire waited gets the same treatment: published, the hold
# would keep its heartbeat and its slot on an instance nobody can release through.
start_error: BaseException | None = None
with self._locks.internal:
if self._closed:
start_error = self._closed_error()
else:
self._hold = hold
self._compromise = None
try:
hold.heartbeat_thread.start()
except BaseException as error: # ruff:ignore[blind-except] # clear the slot below and re-raise
self._hold = None
start_error = error
if start_error is not None:
participant.leave()
raise start_error
return AcquireReturnProxy(lock=self)
def _validate_reentrant(self, mode: Mode, holder: int) -> AcquireReturnProxy:
hold = self._hold
assert hold is not None # ruff:ignore[assert] # callers dispatch here only inside the self._hold is not None branch
if hold.mode != mode:
opposite = "write" if mode == "read" else "read"
direction = "downgrade" if mode == "read" else "upgrade"
msg = (
f"Cannot acquire {mode} lock on {self.lock_file} (lock id: {id(self)}): "
f"already holding a {opposite} lock ({direction} not allowed)"
)
raise RuntimeError(msg)
if mode == "write" and holder != hold.write_thread_id:
msg = (
f"Cannot acquire write lock on {self.lock_file} (lock id: {id(self)}) "
f"from thread {holder} while it is held by thread {hold.write_thread_id}"
)
raise RuntimeError(msg)
# Publishing a hold clears the loss recorded for the one before, so a loss seen here is this hold's. Its
# heartbeat has stopped and a peer may hold the lock, so a new level must not bypass the log.
if (compromise := self._compromise) is not None:
raise _lost_hold_error(self.lock_file, mode, compromise)
if mode == "read":
hold.read_depths[holder] = hold.read_depths.get(holder, 0) + 1
hold.level += 1
return AcquireReturnProxy(lock=self)
def _wait_for(
self,
predicate: Callable[[], bool],
*,
deadline: float | None,
blocking: bool,
cancel_check: Callable[[], bool] | None,
) -> None:
while not predicate():
# The flag is read without the lock here only to stop waiting early; publishing the hold re-checks it.
if self._closed:
raise self._closed_error()
now = time.perf_counter()
if not blocking or (deadline is not None and now >= deadline):
raise Timeout(self.lock_file)
# An abandoned acquire gives up like a timed-out one, so the caller's rollback withdraws its claim.
if cancel_check is not None and cancel_check():
raise Timeout(self.lock_file)
sleep_for = self.poll_interval
if deadline is not None:
sleep_for = min(sleep_for, max(deadline - now, 0.0))
time.sleep(sleep_for)
def _refresh(self, participant: Participant, hold: _Hold) -> bool:
# The loop ends at the first loss, so the holder hears about it once. A transient filesystem error (ESTALE /
# EIO on the NFS-style filesystems this lock targets) is not a loss: retry rather than report a false
# compromise. Report the record unrefreshable only once failures have run long enough that a peer could evict
# it before the next success would land, a margin before the record actually ages out.
try:
outcome, error = participant.heartbeat()
except Exception as failure: # ruff:ignore[blind-except] # the thread would end with the hold still published
self._report_compromise(hold, "refresh-failed", failure)
return False
if outcome == "ok":
hold.last_refresh = time.monotonic()
return True
if outcome == "lost":
self._report_compromise(hold, "evicted", None)
return False
if time.monotonic() - hold.last_refresh >= self.stale_threshold - self.heartbeat_interval:
self._report_compromise(hold, "refresh-failed", error)
return False
return True
def _report_compromise(self, hold: _Hold, reason: CompromiseReason, error: Exception | None) -> None:
# A tick that outlived its release's join must not stamp the old hold's loss onto whatever was acquired since.
with self._locks.internal:
if self._hold is not hold:
return
compromise = LeaseCompromise(
lock_file=self.lock_file, token=hold.participant.token, reason=reason, error=error
)
self._compromise = compromise
if self._on_compromise is not None:
self._on_compromise(compromise)
def _reset_after_fork_in_child(self) -> None: # pragma: forked child
self._locks = _Locks(internal=threading.Lock(), transaction=threading.Lock())
self._hold = None
class _HeartbeatThread(threading.Thread):
def __init__(
self,
refresh: Callable[[], bool],
interval: float,
stop_event: threading.Event,
name: str,
) -> None:
super().__init__(name=name, daemon=True)
self._refresh = refresh
self._interval = interval
self._stop_event = stop_event
def run(self) -> None:
# Set on every exit, an on_compromise that raises included, so nothing waits on a thread that is gone.
try:
while not self._stop_event.wait(self._interval):
if not self._refresh():
return
finally:
self._stop_event.set()
def _lost_hold_error(lock_file: str, mode: Mode, compromise: LeaseCompromise) -> RuntimeError:
return RuntimeError(
f"Cannot acquire {mode} lock on {lock_file}: the current hold was lost ({compromise.reason}), "
"release it before acquiring again"
)
def _validate_intervals(
heartbeat_interval: float, stale_threshold: float | None, poll_interval: float
) -> tuple[float, float, float]:
heartbeat_interval = _seconds("heartbeat_interval", heartbeat_interval)
if not isfinite(heartbeat_interval) or heartbeat_interval <= 0:
msg = f"heartbeat_interval must be positive and finite, got {heartbeat_interval}"
raise ValueError(msg)
# The heartbeat thread waits this long between refreshes, and Event.wait overflows past TIMEOUT_MAX.
_check_timeout_max("heartbeat_interval", heartbeat_interval)
stale_threshold = (
heartbeat_interval * 3 if stale_threshold is None else _seconds("stale_threshold", stale_threshold)
)
if not isfinite(stale_threshold) or stale_threshold <= heartbeat_interval:
msg = (
f"stale_threshold must exceed heartbeat_interval ({heartbeat_interval}) "
f"and be finite, got {stale_threshold}"
)
raise ValueError(msg)
if not isfinite(poll_interval := _seconds("poll_interval", poll_interval)) or poll_interval <= 0:
msg = f"poll_interval must be positive and finite, got {poll_interval}"
raise ValueError(msg)
_check_timeout_max("poll_interval", poll_interval)
# A waiting writer refreshes its record once per poll, so a poll slower than the threshold reads as dead.
if poll_interval >= stale_threshold:
msg = f"poll_interval must be below stale_threshold ({stale_threshold}), got {poll_interval}"
raise ValueError(msg)
return heartbeat_interval, stale_threshold, poll_interval
@dataclass
class _Locks:
internal: threading.Lock
transaction: threading.Lock
@dataclass
class _Hold:
"""Everything that exists only while a lock is held; ``None`` when the instance has no lock."""
level: int
mode: Mode
write_thread_id: int | None
#: Read levels per thread, so a thread can give back only the levels it took.
read_depths: dict[int, int]
participant: Participant
heartbeat_thread: _HeartbeatThread
heartbeat_stop: threading.Event
last_refresh: float
def leave_one_level(self, thread_id: int) -> None:
self.level -= 1
if self.mode == "read":
# The heartbeat thread holds no level of its own, so its release gives back one of a reader's.
owner = thread_id if thread_id in self.read_depths else next(iter(self.read_depths))
if depth := self.read_depths.pop(owner) - 1:
self.read_depths[owner] = depth
def _cleanup_all_instances() -> None: # pragma: no cover - runs from atexit at interpreter shutdown
for instance in list(_ALL_INSTANCES.values()):
with suppress(Exception):
instance.release(force=True)
atexit.register(_cleanup_all_instances)
_register_fork_class(SoftReadWriteLock)
__all__ = [
"SoftReadWriteLock",
"_lost_hold_error",
]