"""Completion notices waiting in the session's inbox. A finished job or background cell whose result nobody read is announced by a notice posted to the session's inbox under a key the kernel chooses, where it waits for a running turn to end. Once everything a notice names has been read here, it is withdrawn by that key, so a notice never outlives the read that satisfies it. Withdrawing one the session already read changes nothing. """ from __future__ import annotations import asyncio import contextlib import uuid from collections.abc import Awaitable, Callable Call = Callable[[str, dict[str, object]], Awaitable[object]] routes: list[Notices] = [] # every route's notices, for `settle` # How a notice ends: the turn it starts may finish without a reply. IDLE = "if nothing else is needed, reply briefly, or await no_reply() to end the turn without a reply." def key() -> str: """A fresh notice key: posting under it twice stores one notice.""" return uuid.uuid4().hex async def settle() -> None: """Withdraw now every notice whose results a cell just read, so the cell's own result cannot reach the session before the withdrawal does.""" for notices in routes: await notices.withdraw() class Notices: """The notices one route (`jobs` or `cells`) posted and still watches.""" def __init__(self, route: str) -> None: self.route = route self.waiting: dict[str, Callable[[], bool]] = {} self.read = asyncio.Event() self.watcher: asyncio.Task[None] | None = None self.call: Call | None = None routes.append(self) def watch(self, call: Call, notice: str | None, read: Callable[[], bool]) -> None: """Watch the notice posted under `notice` until its results are read here; `read` says whether everything it names was read.""" if notice is None: return # nothing was posted self.call = call self.waiting[notice] = read if read(): self.read.set() if self.watcher is None or self.watcher.done(): self.watcher = asyncio.get_running_loop().create_task(self._watch()) def poke(self) -> None: """A result was read here: withdraw the notices it satisfies.""" if self.waiting: self.read.set() async def withdraw(self) -> None: """Withdraw the notices whose results were all read here.""" satisfied = [notice for notice, read in self.waiting.items() if read()] if not satisfied or self.call is None: return for notice in satisfied: self.waiting.pop(notice, None) with contextlib.suppress(Exception): # a host going away keeps them await self.call(f"{self.route}.withdraw", {"keys": satisfied}) async def _watch(self) -> None: while self.waiting: await self.read.wait() self.read.clear() await self.withdraw()