508 lines
20 KiB
Python
508 lines
20 KiB
Python
"""Separate caller cancellation from backend task and executor-future results."""
|
|
|
|
from __future__ import annotations
|
|
|
|
__lazy_modules__ = ["asyncio", "collections", "concurrent.futures", "filelock._error"]
|
|
|
|
import asyncio
|
|
import contextlib
|
|
import time
|
|
from collections import deque
|
|
from concurrent.futures import Future as ConcurrentFuture
|
|
from dataclasses import dataclass
|
|
from threading import Lock
|
|
from typing import TYPE_CHECKING, Final, Generic, Literal, NoReturn, TypeVar, cast
|
|
from weakref import WeakKeyDictionary
|
|
|
|
from filelock._api import (
|
|
_append_exception_context,
|
|
_fork_transition,
|
|
_raise_chained_errors,
|
|
_resolve_read_write_timeout,
|
|
)
|
|
from filelock._error import Timeout
|
|
|
|
if TYPE_CHECKING:
|
|
from collections.abc import AsyncGenerator, Awaitable, Callable
|
|
from concurrent.futures import Executor
|
|
|
|
from filelock._read_write import ReadWriteLock
|
|
from filelock._soft_rw import SoftReadWriteLock
|
|
|
|
_T = TypeVar("_T")
|
|
|
|
#: The holder an async wrapper records its backend level under. No thread has this identifier, so sync code on the
|
|
#: executor thread that took the level cannot re-enter or release it.
|
|
_TASKS_THREAD_ID: Final[int] = 0
|
|
|
|
|
|
class _AsyncTransitionUnavailableError(Exception):
|
|
pass
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class _BackendOutcome(Generic[_T]):
|
|
value: _T | None = None
|
|
error: BaseException | None = None
|
|
|
|
|
|
class _AsyncTransitionGate:
|
|
"""
|
|
First-in, first-out admission for the calls that transition one lock context.
|
|
|
|
Each call queues a ticket, and the head of the queue holds the gate. A call that gives up removes its own ticket,
|
|
so abandoned calls do not pile up behind a long holder.
|
|
"""
|
|
|
|
def __init__(self) -> None:
|
|
self._queue_lock: Final[Lock] = Lock()
|
|
self._queue: Final[deque[ConcurrentFuture[None]]] = deque()
|
|
|
|
@contextlib.asynccontextmanager
|
|
async def hold(self) -> AsyncGenerator[None]:
|
|
ticket: ConcurrentFuture[None] = ConcurrentFuture()
|
|
try:
|
|
self._join(ticket)
|
|
if not ticket.done():
|
|
await self._wait_for_turn(ticket, blocking=True, cancel_check=None, deadline=None, poll_interval=0.05)
|
|
yield
|
|
finally:
|
|
self._leave(ticket)
|
|
|
|
@contextlib.asynccontextmanager
|
|
async def hold_for_acquire(
|
|
self,
|
|
*,
|
|
blocking: bool,
|
|
cancel_check: Callable[[], bool] | None,
|
|
deadline: float | None,
|
|
poll_interval: float,
|
|
) -> AsyncGenerator[None]:
|
|
ticket: ConcurrentFuture[None] = ConcurrentFuture()
|
|
try:
|
|
self._join(ticket)
|
|
if not ticket.done():
|
|
await self._wait_for_turn(
|
|
ticket,
|
|
blocking=blocking,
|
|
cancel_check=cancel_check,
|
|
deadline=deadline,
|
|
poll_interval=poll_interval,
|
|
)
|
|
yield
|
|
finally:
|
|
self._leave(ticket)
|
|
|
|
async def _wait_for_turn(
|
|
self,
|
|
ticket: ConcurrentFuture[None],
|
|
*,
|
|
blocking: bool,
|
|
cancel_check: Callable[[], bool] | None,
|
|
deadline: float | None,
|
|
poll_interval: float,
|
|
) -> None:
|
|
if not blocking:
|
|
raise _AsyncTransitionUnavailableError
|
|
waiter = asyncio.wrap_future(ticket)
|
|
while not ticket.done():
|
|
if cancel_check is not None and cancel_check():
|
|
raise _AsyncTransitionUnavailableError
|
|
wait_interval = poll_interval
|
|
if deadline is not None:
|
|
if (remaining := deadline - time.perf_counter()) <= 0:
|
|
raise _AsyncTransitionUnavailableError
|
|
wait_interval = min(wait_interval, remaining)
|
|
await asyncio.wait((waiter,), timeout=wait_interval)
|
|
# A hand-off that a signal handler's exception cut short leaves the head undone, so the head settles itself.
|
|
self._settle_head()
|
|
|
|
def _join(self, ticket: ConcurrentFuture[None]) -> None:
|
|
with self._queue_lock:
|
|
self._queue.append(ticket)
|
|
if len(self._queue) == 1:
|
|
ticket.set_result(None)
|
|
|
|
def _leave(self, ticket: ConcurrentFuture[None]) -> None:
|
|
with self._queue_lock:
|
|
try:
|
|
self._queue.remove(ticket)
|
|
except ValueError:
|
|
# The join never completed, or this ticket already left.
|
|
return
|
|
self._settle_head_locked()
|
|
|
|
def _settle_head(self) -> None:
|
|
with self._queue_lock:
|
|
self._settle_head_locked()
|
|
|
|
def _settle_head_locked(self) -> None:
|
|
if self._queue and not (head := self._queue[0]).done():
|
|
head.set_result(None)
|
|
|
|
|
|
@dataclass
|
|
class _TaskHold:
|
|
"""
|
|
One task's hold, as the nesting count per wrapper it entered through.
|
|
|
|
A task's hold ends when its last wrapper level is released or closed. Closing one wrapper ends only the levels
|
|
taken through it.
|
|
"""
|
|
|
|
depths: dict[object, int]
|
|
|
|
|
|
class _TaskOwners:
|
|
"""
|
|
Per-task ownership in front of a sync reader/writer lock that tracks threads.
|
|
|
|
An async wrapper runs each call on an executor thread, and that thread does not identify the calling task. Waiting
|
|
writers block new readers so a stream of readers cannot starve them. A thread lock guards the table because tasks on
|
|
different event loops share it. The table stands for one backend level, taken once for all tasks. Sync code can
|
|
end that level directly, with ``close()`` or a forced release on a shared singleton. The next admission then
|
|
forgets the holds instead of letting more tasks join them.
|
|
"""
|
|
|
|
def __init__(self) -> None:
|
|
self._lock: Final[Lock] = Lock()
|
|
self._mode: Literal["read", "write"] | None = None
|
|
self._holds: dict[asyncio.Task[object], _TaskHold] = {}
|
|
self._transitioning = False
|
|
self._waiting_writers = 0
|
|
#: One ticket per waiting call, settled on the next state change. A call that stops waiting takes its own out,
|
|
#: so one that times out or is canceled leaves nothing behind.
|
|
self._waiters: dict[ConcurrentFuture[None], None] = {}
|
|
|
|
async def acquire( # ruff:ignore[too-many-arguments] # one keyword per piece of wrapper state the table consults
|
|
self,
|
|
mode: Literal["read", "write"],
|
|
*,
|
|
timeout: float,
|
|
blocking: bool,
|
|
lock_file: str,
|
|
via: object,
|
|
enter: Callable[[float], Awaitable[None]],
|
|
joinable: Callable[[], bool],
|
|
) -> None:
|
|
task = _current_task()
|
|
timeout = _resolve_read_write_timeout(timeout, blocking=blocking)
|
|
deadline = None if not blocking or timeout < 0 else time.perf_counter() + timeout
|
|
waiting_writer = False
|
|
try:
|
|
while isinstance(
|
|
admission := self._admit(
|
|
task, mode, lock_file, via=via, joinable=joinable, waiting_writer=waiting_writer
|
|
),
|
|
ConcurrentFuture,
|
|
):
|
|
try:
|
|
if not blocking or (deadline is not None and time.perf_counter() >= deadline):
|
|
raise Timeout(lock_file)
|
|
if mode == "write" and not waiting_writer:
|
|
waiting_writer = True
|
|
with self._lock:
|
|
self._waiting_writers += 1
|
|
wait = None if deadline is None else deadline - time.perf_counter()
|
|
await asyncio.wait((asyncio.wrap_future(admission),), timeout=wait)
|
|
finally:
|
|
self._forget(admission)
|
|
finally:
|
|
if waiting_writer:
|
|
with self._lock:
|
|
self._waiting_writers -= 1
|
|
self._notify()
|
|
if admission == "held":
|
|
return
|
|
try:
|
|
await enter(-1 if deadline is None else max(0.0, deadline - time.perf_counter()))
|
|
except BaseException:
|
|
self._finish_transition(mode=None)
|
|
raise
|
|
self._finish_transition(mode=mode, holds={task: _TaskHold(depths={via: 1})})
|
|
|
|
def _admit( # ruff:ignore[too-many-arguments] # the acquire's state, passed through under the table lock
|
|
self,
|
|
task: asyncio.Task[object],
|
|
mode: Literal["read", "write"],
|
|
lock_file: str,
|
|
*,
|
|
via: object,
|
|
joinable: Callable[[], bool],
|
|
waiting_writer: bool,
|
|
) -> Literal["held", "enter"] | ConcurrentFuture[None]:
|
|
with self._lock:
|
|
# A "held" answer trusts the backend level. Once the backend lost it, the holds are gone and the next task
|
|
# has to take the lock again.
|
|
if self._mode is not None and not self._transitioning and not joinable():
|
|
self._holds.clear()
|
|
self._mode = None
|
|
if (hold := self._holds.get(task)) is not None:
|
|
if self._mode != mode:
|
|
msg = (
|
|
f"Cannot acquire {mode} lock on {lock_file}: already holding a "
|
|
f"{'write' if mode == 'read' else 'read'} lock "
|
|
f"({'downgrade' if mode == 'read' else 'upgrade'} not allowed)"
|
|
)
|
|
raise RuntimeError(msg)
|
|
hold.depths[via] = hold.depths.get(via, 0) + 1
|
|
return "held"
|
|
writers_ahead = self._waiting_writers - waiting_writer
|
|
if not self._transitioning:
|
|
if mode == "read" and self._mode == "read" and not writers_ahead:
|
|
self._holds[task] = _TaskHold(depths={via: 1})
|
|
return "held"
|
|
if not self._holds and (mode == "write" or not writers_ahead):
|
|
self._transitioning, self._mode = True, mode
|
|
return "enter"
|
|
return self._ticket()
|
|
|
|
async def release(
|
|
self,
|
|
*,
|
|
force: bool,
|
|
lock_file: str,
|
|
via: object,
|
|
leave: Callable[[], asyncio.Future[_BackendOutcome[None]]],
|
|
still_held: Callable[[], bool],
|
|
) -> None:
|
|
task = _current_task()
|
|
with self._lock:
|
|
if (hold := self._holds.get(task)) is None or via not in hold.depths:
|
|
if force:
|
|
return
|
|
msg = f"Cannot release a lock on {lock_file} that is not held by this task through this wrapper"
|
|
raise RuntimeError(msg)
|
|
if not force and hold.depths[via] > 1:
|
|
hold.depths[via] -= 1
|
|
return
|
|
removed = hold.depths.pop(via)
|
|
if hold.depths:
|
|
return
|
|
del self._holds[task]
|
|
if self._holds:
|
|
return
|
|
self._transitioning = True
|
|
mode = self._mode
|
|
if not still_held():
|
|
self._finish_transition(mode=None)
|
|
msg = f"Cannot release a lock on {lock_file} that is not held by this task"
|
|
raise RuntimeError(msg)
|
|
try:
|
|
cancellation = await _drain_cancellation(leave())
|
|
except BaseException:
|
|
hold.depths[via] = removed
|
|
# Keep the hold for a retried release only while the sync lock still has the level. Restored after the sync
|
|
# lock let go, it would stand for a lock nobody holds.
|
|
self._finish_transition(mode=mode if still_held() else None, holds={task: hold})
|
|
raise
|
|
self._finish_transition(mode=None)
|
|
if cancellation is not None:
|
|
# The release succeeded, so a restored hold would be a phantom no backend call can clear.
|
|
raise cancellation
|
|
|
|
async def retire(
|
|
self,
|
|
via: object | None,
|
|
*,
|
|
leave: Callable[[], asyncio.Future[_BackendOutcome[None]]],
|
|
still_held: Callable[[], bool],
|
|
) -> None:
|
|
"""
|
|
End the holds taken through *via*, or every hold when it is ``None``, as one transition.
|
|
|
|
Leaves the backend through *leave* when that ends the last hold, and always when *via* is ``None``. Arrivals
|
|
wait while it runs, so none joins a hold the backend is letting go of. A transition already under way is waited
|
|
out first: a task entering through *via* must not get a hold after the wrapper is gone. A cancellation is raised
|
|
once the holds are settled.
|
|
"""
|
|
cancellation: asyncio.CancelledError | None = None
|
|
while isinstance(settled := self._drop_holds_via(via), ConcurrentFuture):
|
|
try:
|
|
await _wait_until_done(asyncio.wrap_future(settled))
|
|
except asyncio.CancelledError as error:
|
|
cancellation = error
|
|
finally:
|
|
self._forget(settled)
|
|
mode, dropped = settled
|
|
if via is None or (mode is not None and still_held()):
|
|
try:
|
|
cancellation = await _drain_cancellation(leave()) or cancellation
|
|
except BaseException:
|
|
# A close that failed with the backend still holding stays retryable, as a failed release does.
|
|
self._finish_transition(mode=mode if still_held() else None, holds=dropped)
|
|
raise
|
|
self._finish_transition(mode=None)
|
|
elif mode is not None:
|
|
# Sync code already ended the level taken for tasks, so there is nothing to give back.
|
|
self._finish_transition(mode=None)
|
|
if cancellation is not None:
|
|
raise cancellation
|
|
|
|
def _drop_holds_via(
|
|
self, via: object | None
|
|
) -> tuple[Literal["read", "write"] | None, dict[asyncio.Task[object], _TaskHold]] | ConcurrentFuture[None]:
|
|
# Returns the future a running transition settles, or else the mode to leave (None when other holds keep the
|
|
# backend level) and the dropped holds. The table stays transitioning while that mode is left.
|
|
with self._lock:
|
|
if self._transitioning:
|
|
return self._ticket()
|
|
if via is None:
|
|
dropped = dict(self._holds)
|
|
self._holds.clear()
|
|
else:
|
|
dropped = {}
|
|
for task, hold in list(self._holds.items()):
|
|
if (count := hold.depths.pop(via, None)) is not None:
|
|
dropped[task] = _TaskHold(depths={via: count})
|
|
if not hold.depths:
|
|
del self._holds[task]
|
|
if self._holds and via is not None:
|
|
return None, dropped
|
|
mode = self._mode
|
|
self._transitioning = mode is not None or via is None
|
|
return mode, dropped
|
|
|
|
def _finish_transition(
|
|
self, *, mode: Literal["read", "write"] | None, holds: dict[asyncio.Task[object], _TaskHold] | None = None
|
|
) -> None:
|
|
with self._lock:
|
|
self._transitioning, self._mode = False, mode
|
|
if mode is not None and holds:
|
|
for task, hold in holds.items():
|
|
self._holds.setdefault(task, _TaskHold(depths={})).depths.update(hold.depths)
|
|
self._notify()
|
|
|
|
def _ticket(self) -> ConcurrentFuture[None]:
|
|
# Called under the table lock, in the section that decided to wait, so no state change slips in between.
|
|
ticket: ConcurrentFuture[None] = ConcurrentFuture()
|
|
self._waiters[ticket] = None
|
|
return ticket
|
|
|
|
def _forget(self, ticket: ConcurrentFuture[None]) -> None:
|
|
with self._lock:
|
|
self._waiters.pop(ticket, None)
|
|
|
|
def _notify(self) -> None:
|
|
waiters, self._waiters = self._waiters, {}
|
|
for ticket in waiters:
|
|
ticket.set_result(None)
|
|
|
|
|
|
_TASK_OWNERS: Final[WeakKeyDictionary[ReadWriteLock | SoftReadWriteLock, _TaskOwners]] = WeakKeyDictionary()
|
|
_TASK_OWNERS_LOCK: Final[Lock] = Lock()
|
|
|
|
|
|
def _task_owners_for(sync_lock: ReadWriteLock | SoftReadWriteLock) -> _TaskOwners:
|
|
"""Singleton wrappers share one sync lock, so they must share its task holds too."""
|
|
with _fork_transition(), _TASK_OWNERS_LOCK:
|
|
if (owners := _TASK_OWNERS.get(sync_lock)) is None:
|
|
owners = _TASK_OWNERS[sync_lock] = _TaskOwners()
|
|
return owners
|
|
|
|
|
|
def _current_task() -> asyncio.Task[object]:
|
|
if (task := asyncio.current_task()) is None:
|
|
msg = "an async reader/writer lock must be used from inside an asyncio task"
|
|
raise RuntimeError(msg)
|
|
return task
|
|
|
|
|
|
async def _drain_cancellation(future: asyncio.Future[_BackendOutcome[None]]) -> asyncio.CancelledError | None:
|
|
# Returned, not raised, so the caller can tell a call that completed under cancellation from one that failed.
|
|
try:
|
|
await _wait_until_done(future)
|
|
except asyncio.CancelledError as cancellation:
|
|
try:
|
|
await _drain_future(future)
|
|
except BaseException as error: # ruff:ignore[blind-except] # reported with the cancellation below
|
|
_raise_cancelled_error(cancellation, error)
|
|
return cancellation
|
|
_future_result(future)
|
|
return None
|
|
|
|
|
|
async def _drain_future(future: asyncio.Future[_BackendOutcome[_T]]) -> _T:
|
|
while not future.done():
|
|
with contextlib.suppress(asyncio.CancelledError):
|
|
await _wait_until_done(future)
|
|
return _future_result(future)
|
|
|
|
|
|
async def _wait_until_done(future: asyncio.Future[_T]) -> None:
|
|
if not future.done():
|
|
await asyncio.wait((future,))
|
|
|
|
|
|
def _future_result(future: asyncio.Future[_BackendOutcome[_T]]) -> _T:
|
|
outcome = future.result()
|
|
if (error := outcome.error) is None:
|
|
return cast("_T", outcome.value)
|
|
context = error.__context__
|
|
try:
|
|
raise error # ruff:ignore[raise-within-try] # the handler restores context changed across the async boundary
|
|
except BaseException:
|
|
error.__context__ = context
|
|
raise
|
|
|
|
|
|
def _run_in_executor(
|
|
loop: asyncio.AbstractEventLoop, executor: Executor | None, func: Callable[[], _T]
|
|
) -> asyncio.Future[_BackendOutcome[_T]]:
|
|
outcome: asyncio.Future[_BackendOutcome[_T]] = loop.create_future()
|
|
|
|
def settle(call: asyncio.Future[_BackendOutcome[_T]]) -> None:
|
|
try:
|
|
result = call.result()
|
|
except asyncio.CancelledError:
|
|
# shutdown(cancel_futures=True) dropped the call unrun: a CancelledError would cancel a task nobody canceled
|
|
# and hide that the lock state never changed.
|
|
msg = "the executor shut down before running the lock backend call"
|
|
result = _BackendOutcome(error=RuntimeError(msg))
|
|
outcome.set_result(result)
|
|
|
|
loop.run_in_executor(executor, _capture_call, func).add_done_callback(settle)
|
|
return outcome
|
|
|
|
|
|
def _capture_call(func: Callable[[], _T]) -> _BackendOutcome[_T]:
|
|
try:
|
|
return _BackendOutcome(value=func())
|
|
except BaseException as error: # ruff:ignore[blind-except] # backend control-flow exceptions are operation results
|
|
return _BackendOutcome(error=error)
|
|
|
|
|
|
def _raise_cancelled_error(cancellation: asyncio.CancelledError, error: BaseException) -> NoReturn:
|
|
# A reconciliation step failed while unwinding a cancellation, so keep both exception chains. Splice the error's
|
|
# existing context onto the cancellation, then make the cancellation the error's context, so both the failure and
|
|
# the cancellation that triggered it survive. Shared by the async wrappers so cancellations report the same way.
|
|
if (context := error.__context__) is not None and context is not cancellation:
|
|
if (cancellation_context := cancellation.__context__) is not None:
|
|
_append_exception_context(context, cancellation_context)
|
|
cancellation.__context__ = context
|
|
error.__context__ = cancellation
|
|
_raise_chained_errors(error)
|
|
|
|
|
|
async def _capture_awaitable(awaitable: Awaitable[_T]) -> _BackendOutcome[_T]:
|
|
try:
|
|
return _BackendOutcome(value=await awaitable)
|
|
except BaseException as error: # ruff:ignore[blind-except] # backend cancellation must remain distinct from caller cancellation
|
|
return _BackendOutcome(error=error)
|
|
|
|
|
|
__all__ = [
|
|
"_TASKS_THREAD_ID",
|
|
"_AsyncTransitionGate",
|
|
"_AsyncTransitionUnavailableError",
|
|
"_BackendOutcome",
|
|
"_capture_awaitable",
|
|
"_capture_call",
|
|
"_drain_future",
|
|
"_future_result",
|
|
"_raise_cancelled_error",
|
|
"_run_in_executor",
|
|
"_task_owners_for",
|
|
"_wait_until_done",
|
|
]
|