150 lines
5.6 KiB
Python
Vendored
150 lines
5.6 KiB
Python
Vendored
# MIT License
|
|
#
|
|
# Copyright The SCons Foundation
|
|
|
|
"""SCons file locking functions.
|
|
|
|
Simple-minded filesystem-based locking. Provides a context manager
|
|
which acquires a lock (or at least, permission) on entry and
|
|
releases it on exit.
|
|
|
|
Usage::
|
|
|
|
from SCons.Util.filelock import FileLock
|
|
|
|
with FileLock("myfile.txt", writer=True) as lock:
|
|
print(f"Lock on {lock.file} acquired.")
|
|
# work with the file as it is now locked
|
|
"""
|
|
|
|
# TODO: things to consider.
|
|
# Is raising an exception the right thing for failing to get lock?
|
|
# Is a filesystem lockfile scheme sufficient for our needs?
|
|
# - or is it better to put locks on the actual file (fcntl/windows-based)?
|
|
# ... Is that even viable in the case of a remote (network) file?
|
|
# Is this safe enough? Or do we risk dangling lockfiles?
|
|
# Permission issues in case of multi-user. This *should* be okay,
|
|
# the cache usually goes in user's homedir, plus you already have
|
|
# enough rights for the lockfile if the dir lets you create the cache.
|
|
# Need a forced break-lock method?
|
|
# The lock attributes could probably be made opaque. Showed one visible
|
|
# in the example above, but not sure the benefit of that.
|
|
|
|
import os
|
|
import time
|
|
from typing import Optional
|
|
|
|
|
|
class SConsLockFailure(Exception):
|
|
"""Lock failure exception."""
|
|
|
|
|
|
class FileLock:
|
|
"""Lock a file using a lockfile.
|
|
|
|
Basic locking for when multiple processes may hit an externally
|
|
shared resource that cannot depend on locking within a single SCons
|
|
process. SCons does not have a lot of those, but caches come to mind.
|
|
|
|
Cross-platform safe, does not use any OS-specific features. Provides
|
|
context manager support, or can be called with :meth:`acquire_lock`
|
|
and :meth:`release_lock`.
|
|
|
|
Lock can be a write lock, which is held until released, or a read
|
|
lock, which releases immediately upon aquisition - we want to not
|
|
read a file which somebody else may be writing, but not create the
|
|
writers starvation problem of the classic readers/writers lock.
|
|
|
|
TODO: Should default timeout be None (non-blocking), or 0 (block forever),
|
|
or some arbitrary number?
|
|
|
|
Arguments:
|
|
file: name of file to lock. Only used to build the lockfile name.
|
|
timeout: optional time (sec) to give up trying.
|
|
If ``None``, quit now if we failed to get the lock (non-blocking).
|
|
If 0, block forever (well, a long time).
|
|
delay: optional delay between tries [default 0.05s]
|
|
writer: if True, obtain the lock for safe writing. If False (default),
|
|
just wait till the lock is available, give it back right away.
|
|
|
|
Raises:
|
|
SConsLockFailure: if the operation "timed out", including the
|
|
non-blocking mode.
|
|
"""
|
|
|
|
def __init__(
|
|
self,
|
|
file: str,
|
|
timeout: Optional[int] = None,
|
|
delay: Optional[float] = 0.05,
|
|
writer: bool = False,
|
|
) -> None:
|
|
if timeout is not None and delay is None:
|
|
raise ValueError("delay cannot be None if timeout is None.")
|
|
# It isn't completely obvious where to put the lockfile.
|
|
# This scheme depends on diffrent processes using the same path
|
|
# to the lockfile, since the lockfile is the magic resource,
|
|
# not the file itself. getcwd() is no good for testcases, each of
|
|
# which run in a unique test directory. tempfile is no good,
|
|
# as those are (intentionally) unique per process.
|
|
# Our simple first guess is just put it where the file is.
|
|
self.file = file
|
|
self.lockfile = f"{file}.lock"
|
|
self.lock: Optional[int] = None
|
|
self.timeout = 999999 if timeout == 0 else timeout
|
|
self.delay = 0.0 if delay is None else delay
|
|
self.writer = writer
|
|
|
|
def acquire_lock(self) -> None:
|
|
"""Acquire the lock, if possible.
|
|
|
|
If the lock is in use, check again every *delay* seconds.
|
|
Continue until lock acquired or *timeout* expires.
|
|
"""
|
|
start_time = time.perf_counter()
|
|
while True:
|
|
try:
|
|
self.lock = os.open(self.lockfile, os.O_CREAT|os.O_EXCL|os.O_RDWR)
|
|
except (FileExistsError, PermissionError) as exc:
|
|
if self.timeout is None:
|
|
raise SConsLockFailure(
|
|
f"Could not acquire lock on {self.file!r}"
|
|
) from exc
|
|
if (time.perf_counter() - start_time) > self.timeout:
|
|
raise SConsLockFailure(
|
|
f"Timeout waiting for lock on {self.file!r}."
|
|
) from exc
|
|
time.sleep(self.delay)
|
|
else:
|
|
if not self.writer:
|
|
# reader: waits to get lock, but doesn't hold it
|
|
self.release_lock()
|
|
break
|
|
|
|
def release_lock(self) -> None:
|
|
"""Release the lock by deleting the lockfile."""
|
|
if self.lock:
|
|
os.close(self.lock)
|
|
os.unlink(self.lockfile)
|
|
self.lock = None
|
|
|
|
def __enter__(self) -> "FileLock":
|
|
"""Context manager entry: acquire lock if not holding."""
|
|
if not self.lock:
|
|
self.acquire_lock()
|
|
return self
|
|
|
|
def __exit__(self, exc_type, exc_value, exc_tb) -> None:
|
|
"""Context manager exit: release lock if holding."""
|
|
if self.lock:
|
|
self.release_lock()
|
|
|
|
def __repr__(self) -> str:
|
|
"""Nicer display if someone repr's the lock class."""
|
|
return (
|
|
f"{self.__class__.__name__}("
|
|
f"file={self.file!r}, "
|
|
f"timeout={self.timeout!r}, "
|
|
f"delay={self.delay!r}, "
|
|
f"writer={self.writer!r})"
|
|
)
|