pyfect-dev 0.1.0__py3-none-any.whl

pyfect/batching/_engine.py

@@ -0,0 +1,229 @@
+"""Collecting requests into batches and running them (Effect's
+``internal/request.ts``).
+
+A request joins its resolver's pending batch for its key, or starts one.
+A new batch starts a root fiber that waits out the resolver's ``delay``
+and then runs the batch; a request that makes ``collect_while`` say no
+interrupts that wait and runs the batch at once. A batch runs on a root
+fiber with the services of the request that started it.
+
+An interrupted caller leaves its batch; the last one to leave interrupts
+the batch's wait, so the batch never runs.
+
+Pending batches are kept per run as well as per key: a ``run_blocking``'s
+scheduler stops when the run ends, so a batch a daemon left behind there
+would never run, and a later run joining it would wait forever.
+"""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from collections.abc import Callable, Hashable
+from dataclasses import dataclass
+from types import NoneType
+from typing import Any, Final, final
+
+from pyfect._core import Effect, _Callback, _FromExit, _Succeed, _Suspend, _Sync, _WithFiber
+from pyfect._fiber import Fiber
+from pyfect._root import new_root, run_identity, start_root
+from pyfect.batching._request import Entry, EqualKeys
+from pyfect.batching._resolver import RequestResolver
+from pyfect.context import Context
+from pyfect.exit import Exit, Failure
+from pyfect.exit import die as exit_die
+from pyfect.exit import interrupt as exit_interrupt
+from pyfect.scheduler import Scheduler
+
+_VOID: Final[Effect[None]] = _Succeed(None)
+
+
+class UncompletedRequestError(RuntimeError):
+    """The defect a request dies with when its batch ran to the end
+    without completing it."""
+
+    def __init__(self, request: object) -> None:
+        super().__init__(f"Effect.request: RequestResolver did not complete request {request!r}")
+        self.request = request
+
+
+@dataclass(frozen=True, slots=True)
+class Origin:
+    """Where a request was made: the services and run of its fiber, the
+    fiber's id (``None`` outside a fiber) and whether a root fiber started
+    from there runs at once."""
+
+    context: Context
+    run_scheduler: Scheduler
+    fiber_id: int | None
+    now: bool = False
+
+    def slot(self, key: Hashable) -> Slot:
+        """Where the pending batch for ``key`` made from here is kept."""
+        return (run_identity(self.run_scheduler), key)
+
+
+@final
+class _ByReference:
+    """A key that matches only itself, and keeps it alive while it is pending."""
+
+    __slots__ = ("key",)
+
+    def __init__(self, key: object) -> None:
+        self.key = key
+
+    def __eq__(self, other: object) -> bool:
+        return isinstance(other, _ByReference) and other.key is self.key
+
+    def __hash__(self) -> int:
+        return id(self.key)
+
+
+def _slot_key(resolver: RequestResolver[Any, Any], key: Hashable) -> Hashable:
+    if isinstance(resolver.batch_key, EqualKeys) or isinstance(
+        key, str | bytes | int | float | NoneType
+    ):
+        return key
+    return _ByReference(key)
+
+
+type Slot = tuple[object, Hashable]
+"""A pending batch's place in its resolver: its run and its key."""
+
+
+class Batch:
+    """A resolver's batch for one key. ``entries`` are what ``run_all``
+    gets; ``pending`` are the entries whose callers still wait for this
+    batch to complete them."""
+
+    __slots__ = ("entries", "fiber", "key", "origin", "pending", "resolver", "slot")
+
+    def __init__(self, resolver: RequestResolver[Any, Any], key: Hashable, origin: Origin) -> None:
+        self.resolver = resolver
+        self.key = key
+        self.origin = origin
+        self.slot = origin.slot(_slot_key(resolver, key))
+        # Dicts as insertion-ordered sets.
+        self.entries: dict[Entry[Any], None] = {}
+        self.pending: dict[Entry[Any], None] = {}
+        self.fiber: Fiber[Any, Any] | None = None
+
+    def wait_then_run(self) -> Effect[None]:
+        """The delay fiber's effect."""
+
+        def wait(fiber: Fiber[Any, Any]) -> Effect[None]:
+            # A delay that makes requests itself may fill this batch and
+            # interrupt this fiber before ``start_root`` returns.
+            self.fiber = fiber
+            return self.resolver.delay
+
+        return _WithFiber(wait).flat_map(lambda _: self.take())
+
+    def take(self) -> Effect[None, Any]:
+        """Remove the batch from its resolver and give the effect that runs
+        it, unless it was removed already (cancelled, or run)."""
+        batches = self.resolver._batches
+        if batches.get(self.slot) is not self:
+            return _VOID
+        del batches[self.slot]
+        return _Suspend(lambda: self.resolver.run_all(list(self.entries), self.key)).on_exit(
+            self._finish
+        )
+
+    def _finish(self, ex: Exit[None, Any]) -> Effect[None]:
+        for entry in list(self.pending):
+            entry._complete(
+                exit_die(UncompletedRequestError(entry.request))
+                if not isinstance(ex, Failure)
+                else ex
+            )
+        self.entries.clear()
+        return _VOID
+
+
+def add_entry(
+    resolver: RequestResolver[Any, Any],
+    request: object,
+    resume: Callable[[Exit[Any, Any]], None],
+    origin: Origin,
+) -> Entry[Any]:
+    """Add a request to its batch. ``resume`` gets its exit, once, unless
+    the caller left first."""
+    batch: Batch | None = None
+    completed = False
+
+    def complete(ex: Exit[Any, Any]) -> None:
+        nonlocal completed
+        if completed:
+            return
+        completed = True
+        # A removed entry still reaches resolver hooks (``with_cache``
+        # wraps this function), but not its caller, who has left.
+        if batch is not None:
+            if entry not in batch.pending:
+                return
+            del batch.pending[entry]
+        resume(ex)
+
+    entry = Entry[Any](request, context=origin.context, complete_unsafe=complete)
+    if resolver.pre_check is not None and not resolver.pre_check(entry):
+        return entry
+    key = resolver.batch_key(entry)
+    slot = origin.slot(_slot_key(resolver, key))
+    batches = resolver._batches
+    batch = batches.get(slot)
+    if batch is None:
+        batch = batches[slot] = Batch(resolver, key, origin)
+        batch.pending[entry] = None
+        batch.entries[entry] = None
+        delay_fiber: Fiber[Any, Any] = new_root(origin.run_scheduler, origin.context)
+        batch.fiber = delay_fiber
+        start_root(delay_fiber, batch.wait_then_run(), now=origin.now)
+        # A delay that ended at once has run (and removed) the batch.
+        if completed or batches.get(slot) is not batch:
+            return entry
+    else:
+        batch.pending[entry] = None
+        batch.entries[entry] = None
+    if resolver.collect_while(batch.entries.keys()):
+        return entry
+    assert batch.fiber is not None
+    batch.fiber.interrupt_as_unsafe(origin.fiber_id)
+    first = batch.origin
+    start_root(new_root(first.run_scheduler, first.context), batch.take(), now=origin.now)
+    return entry
+
+
+def remove_entry(resolver: RequestResolver[Any, Any], entry: Entry[Any], origin: Origin) -> None:
+    """The caller of ``entry`` (made from ``origin``) left: take the entry
+    out of its batch and interrupt the batch's wait if no entry is left."""
+    if entry.uninterruptible:
+        return
+    slot = origin.slot(_slot_key(resolver, resolver.batch_key(entry)))
+    batch = resolver._batches.get(slot)
+    if batch is None or entry not in batch.entries:
+        return
+    del batch.entries[entry]
+    batch.pending.pop(entry, None)
+    abandoned = None
+    if not batch.entries:
+        del resolver._batches[slot]
+        abandoned = batch.fiber
+    # The wait's finalizers may make requests, so complete the entry first.
+    entry._complete(exit_interrupt())
+    if abandoned is not None:
+        abandoned.interrupt_as_unsafe(None)
+
+
+def request_with(req: object, resolver: RequestResolver[Any, Any]) -> Effect[Any, Any, Any]:
+    """Make ``req`` from the running fiber and wait for its exit."""
+
+    def body(fiber: Fiber[Any, Any]) -> Effect[Any, Any, Any]:
+        origin = Origin(fiber._context, fiber._run_scheduler, fiber.id)
+
+        def register(resume: Callable[[Effect[Any, Any, Any]], None]) -> Effect[None]:
+            entry = add_entry(resolver, req, lambda ex: resume(_FromExit(ex)), origin)
+            return _Sync(lambda: remove_entry(resolver, entry, origin))
+
+        return _Callback(register)
+
+    return _WithFiber(body)

pyfect/batching/_from_effect.py

@@ -0,0 +1,76 @@
+"""``RequestResolver.from_effect`` and ``from_effect_tagged``."""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable, Mapping, Sequence
+from typing import Any
+
+from pyfect._concurrency import for_each
+from pyfect._core import Effect, _Callback, _Locally, _Succeed, _WithFiber
+from pyfect._fiber import Fiber
+from pyfect.batching._request import Entry
+from pyfect.batching._resolver import RequestResolver
+from pyfect.cause import Cause
+from pyfect.exit import Exit, Failure, Success
+
+
+def from_effect[Q, E](f: Callable[[Entry[Q]], Effect[object, E]]) -> RequestResolver[Q, E]:
+    def run_all(entries: Sequence[Entry[Q]]) -> Effect[None, E]:
+        def body(parent: Fiber[Any, Any]) -> Effect[None, E]:
+            def register(resume: Callable[[Effect[None]], None]) -> None:
+                remaining = len(entries)
+                for entry in entries:
+                    # Children of the batch's fiber, so interrupting the
+                    # batch interrupts them.
+                    child = parent._fork(
+                        _Locally(f(entry), _replace_with(entry)),
+                        daemon=False,
+                        start_immediately=True,
+                    )
+
+                    def observe(ex: Exit[Any, Any], entry: Entry[Any] = entry) -> None:
+                        nonlocal remaining
+                        entry._complete(ex)
+                        remaining -= 1
+                        if remaining == 0:
+                            resume(_Succeed(None))
+
+                    child.add_observer_unsafe(observe)
+
+            return _Callback(register)
+
+        return _WithFiber(body)
+
+    return RequestResolver(run_all)
+
+
+def _replace_with(entry: Entry[Any]) -> Callable[[Any], Any]:
+    """Run with exactly the services of the fiber that made the request."""
+    return lambda _current: entry.context
+
+
+def from_effect_tagged[Q, E](
+    handlers: Mapping[type[Q], Callable[[Sequence[Entry[Any]]], Effect[Iterable[object], E]]],
+) -> RequestResolver[Q, E]:
+    def run_all(entries: Sequence[Entry[Q]]) -> Effect[None]:
+        groups: dict[type[Any], list[Entry[Any]]] = {}
+        for entry in entries:
+            groups.setdefault(type(entry.request), []).append(entry)
+
+        def run_group(group: tuple[type[Any], list[Entry[Any]]]) -> Effect[None]:
+            cls, members = group
+
+            def failed(cause: Cause[Any]) -> None:
+                for entry in members:
+                    entry._complete(Failure(cause))
+
+            def succeeded(values: Iterable[object]) -> None:
+                for entry, value in zip(members, values, strict=False):
+                    entry._complete(Success(value))
+
+            return handlers[cls](members).match_cause(on_failure=failed, on_success=succeeded)
+
+        return for_each(groups.items(), run_group, concurrency="unbounded").as_void()
+
+    return RequestResolver(run_all)

pyfect/batching/_persisted.py

@@ -0,0 +1,98 @@
+"""``RequestResolver.persisted``: outcomes kept in a persistence store."""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from collections.abc import Callable, Generator, Hashable, Sequence
+from typing import Any, Never
+
+from pyfect._context_effects import provide_context
+from pyfect._core import Effect, _call_user
+from pyfect.batching._request import Entry
+from pyfect.batching._resolver import RequestResolver
+from pyfect.duration import Duration
+from pyfect.effect import gen, void
+from pyfect.exit import Exit, Failure
+from pyfect.persistence.persistable import AnyPersistable
+from pyfect.persistence.persistence import Persistence, PersistenceStore
+from pyfect.scope import Scope
+
+
+def persisted[Q: AnyPersistable](
+    resolver: RequestResolver[Q, Any],
+    store_id: str,
+    time_to_live: Callable[[Exit[Any, Any], Q], Duration] | None,
+    stale_while_revalidate: Callable[[Exit[Any, Any], Q], bool] | None,
+) -> Effect[RequestResolver[Q, Any], Never, Persistence | Scope]:
+    def build() -> Generator[Effect[Any, Never, Any], Any, RequestResolver[Q, Any]]:
+        persistence = yield from Persistence()
+        store = yield from persistence.make(
+            store_id=store_id,
+            time_to_live=time_to_live,
+        )
+        return resolver._with(run_all=_run_all(resolver, store, stale_while_revalidate))
+
+    return gen(build)
+
+
+def _run_all[Q: AnyPersistable](
+    resolver: RequestResolver[Q, Any],
+    store: PersistenceStore,
+    stale_while_revalidate: Callable[[Exit[Any, Any], Q], bool] | None,
+) -> Callable[[Sequence[Entry[Q]], Hashable], Effect[None, Any]]:
+    run_all = resolver.run_all
+
+    def wrapped(entries: Sequence[Entry[Q]], key: Hashable) -> Effect[None, Any]:
+        context = entries[0].context
+
+        def body() -> Generator[Effect[Any, Any, Any], Any]:
+            results = yield from store.get_many([entry.request for entry in entries]).pipe(
+                provide_context(context)
+            )
+            leftover: list[Entry[Q]] = []
+            to_persist: dict[Q, Exit[Any, Any]] = {}
+            completed: set[int] = set()
+            for entry, stored in zip(entries, results, strict=True):
+                stale = (
+                    stored is not None
+                    and stale_while_revalidate is not None
+                    and stale_while_revalidate(stored, entry.request)
+                )
+                if stored is not None and not stale:
+                    entry._complete(stored)
+                    continue
+                # A stale outcome answers now; the refreshed one is stored.
+                if stored is not None:
+                    entry._complete(stored)
+                entry._complete = _recording(entry, completed, to_persist)
+                leftover.append(entry)
+            if not leftover:
+                return
+
+            def fail_unfinished(cause: Any) -> Effect[None]:
+                for entry in leftover:
+                    if id(entry) not in completed:
+                        entry._complete(Failure(cause))
+                return void
+
+            yield from _call_user(run_all, leftover, key).catch_cause(fail_unfinished)
+            yield from store.set_many(to_persist.items()).pipe(provide_context(context))
+
+        return gen(body)
+
+    return wrapped
+
+
+def _recording[Q](
+    entry: Entry[Q], completed: set[int], to_persist: dict[Q, Exit[Any, Any]]
+) -> Callable[[Exit[Any, Any]], None]:
+    """``entry``'s completion, also noting the entry as completed and its
+    outcome as one to store."""
+    complete = entry._complete
+
+    def record(ex: Exit[Any, Any]) -> None:
+        completed.add(id(entry))
+        to_persist[entry.request] = ex
+        complete(ex)
+
+    return record

pyfect/batching/_request.py

@@ -0,0 +1,133 @@
+"""``Request[A, E, R]`` and the ``Entry`` a resolver completes."""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from collections.abc import Callable, Hashable
+from typing import Any, Generic, Never, Protocol, Self, TypeVar, final
+
+from pyfect._core import Effect, _Succeed, _Sync
+from pyfect._effect_args import require_effect
+from pyfect.cause import Cause
+from pyfect.context import Context
+from pyfect.exit import Exit, Failure, Success
+from pyfect.exit import fail as exit_fail
+
+A_co = TypeVar("A_co", covariant=True)
+E_co = TypeVar("E_co", covariant=True, default=Never)
+R_co = TypeVar("R_co", covariant=True, default=Never)
+Q_co = TypeVar("Q_co", covariant=True)
+_A_co = TypeVar("_A_co", covariant=True)
+_E_co = TypeVar("_E_co", covariant=True)
+_R_co = TypeVar("_R_co", covariant=True)
+
+
+class Request(Generic[A_co, E_co, R_co]):
+    """A request that succeeds with ``A``, fails with ``E`` and needs the
+    services ``R``. Subclass it as a frozen dataclass, so equal requests
+    compare equal (``with_cache`` and grouping rely on it)::
+
+        @dataclass(frozen=True)
+        class GetUser(fx.Request[User, NotFound]):
+            id: int
+    """
+
+    __slots__ = ()
+
+    def _request_types(self) -> tuple[A_co, E_co, R_co, Self]:
+        """Never called: lets ``request`` read ``A``, ``E``, ``R`` and the
+        request's own class from one argument."""
+        raise NotImplementedError
+
+
+class TypedRequest(Protocol[_A_co, _E_co, _R_co, Q_co]):
+    """A ``Request[A, E, R]`` whose class is ``Q``."""
+
+    def _request_types(self) -> tuple[_A_co, _E_co, _R_co, Q_co]: ...
+
+
+class Entry(Generic[Q_co]):
+    """One pending request inside a batch: the request, the services of
+    the fiber that made it, and the way to complete it.
+
+    Resolvers complete each entry once; later completions are ignored.
+    ``uninterruptible`` keeps the entry in its batch when its caller is
+    interrupted (``with_cache`` sets it on a request others wait for)."""
+
+    __slots__ = ("_complete", "_context", "_request", "uninterruptible")
+
+    def __init__(
+        self,
+        request: Q_co,
+        *,
+        context: Context,
+        complete_unsafe: Callable[[Exit[Any, Any]], None],
+        uninterruptible: bool = False,
+    ) -> None:
+        self._request = request
+        self._context = context
+        self._complete = complete_unsafe
+        self.uninterruptible = uninterruptible
+
+    @property
+    def request(self) -> Q_co:
+        return self._request
+
+    @property
+    def context(self) -> Context:
+        """The services of the fiber that made the request."""
+        return self._context
+
+    def complete_unsafe[A, E](self: Entry[Request[A, E, Any]], ex: Exit[A, E], /) -> None:
+        """Complete the request now with ``ex``."""
+        self._complete(ex)
+
+    def complete[A, E](self: Entry[Request[A, E, Any]], ex: Exit[A, E], /) -> Effect[None]:
+        """The effect that completes the request with ``ex``."""
+        return _Sync(lambda: self._complete(ex))
+
+    def complete_effect[A, E, R](
+        self: Entry[Request[A, E, Any]], eff: Effect[A, E, R], /
+    ) -> Effect[None, Never, R]:
+        """Run ``eff`` and complete the request with its value or typed
+        error. Defects and interruptions are not caught."""
+        require_effect(eff, "eff")
+        complete = self._complete
+
+        def done(ex: Exit[Any, Any]) -> Effect[None]:
+            complete(ex)
+            return _VOID
+
+        return eff.match_effect(
+            on_failure=lambda e: done(exit_fail(e)), on_success=lambda a: done(Success(a))
+        )
+
+    def succeed[A](self: Entry[Request[A, Any, Any]], value: A, /) -> Effect[None]:
+        return _Sync(lambda: self._complete(Success(value)))
+
+    def fail[E](self: Entry[Request[Any, E, Any]], error: E, /) -> Effect[None]:
+        return _Sync(lambda: self._complete(exit_fail(error)))
+
+    def fail_cause[E](self: Entry[Request[Any, E, Any]], cause: Cause[E], /) -> Effect[None]:
+        return _Sync(lambda: self._complete(Failure(cause)))
+
+    def __repr__(self) -> str:
+        return f"Entry({self._request!r})"
+
+
+_VOID: Effect[None] = _Succeed(None)
+
+
+@final
+class EqualKeys[Q]:
+    """A batch key function whose keys compare with ``==`` (Effect's
+    ``equalBatchKeys``, ``RequestResolver.grouped``). Every other key function's
+    keys compare as a JavaScript ``Map`` compares them."""
+
+    __slots__ = ("__weakref__", "f")
+
+    def __init__(self, f: Callable[[Entry[Q]], Hashable]) -> None:
+        self.f = f
+
+    def __call__(self, entry: Entry[Q]) -> Hashable:
+        return self.f(entry)