pyfect-dev 0.1.0__py3-none-any.whl

pyfect/reactivity/atom_ref.py

@@ -0,0 +1,260 @@
+"""``AtomRef``: a plain observable value outside any registry (Effect's
+``effect/reactivity/AtomRef``).
+
+``make(value)`` is a ref you ``set`` and ``subscribe`` to; ``prop(key)``
+focuses on one field (a mapping key, a sequence index or a dataclass
+field), ``map(f)`` derives a read-only ref, and ``collection(items)`` is a
+list of refs that hears of changes to any of them. Setting an equal value
+(``Equal``) notifies nobody.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import itertools
+from collections.abc import Callable, Iterable, Mapping
+from typing import Any, Self, cast
+
+from pyfect import _equal
+from pyfect._public import publish
+
+_keys = itertools.count()
+
+
+def _new_key() -> str:
+    return f"AtomRef-{next(_keys)}"
+
+
+class _Listener[A]:
+    __slots__ = ("f", "next", "prev")
+
+    def __init__(self, f: Callable[[A], None], next_: _Listener[A] | None) -> None:
+        self.f = f
+        self.prev: _Listener[A] | None = None
+        self.next = next_
+
+
+class ReadonlyRef[A]:
+    """A value that can be read and subscribed to."""
+
+    key: str
+
+    @property
+    def value(self) -> A:
+        raise NotImplementedError
+
+    def subscribe(self, f: Callable[[A], None]) -> Callable[[], None]:
+        """Call ``f`` with each new value; returns the unsubscribe."""
+        raise NotImplementedError
+
+    def map[B](self, f: Callable[[A], B]) -> ReadonlyRef[B]:
+        """A ref of ``f`` of this one's value, notifying when it changes."""
+        return _MapRef(self, f)
+
+    def __eq__(self, other: object) -> bool:
+        return isinstance(other, ReadonlyRef) and _equal.equals(
+            self.value, cast("ReadonlyRef[Any]", other).value
+        )
+
+    def __hash__(self) -> int:
+        return hash(_equal.equal_key(self.value))
+
+
+class _SourceRef[A](ReadonlyRef[A]):
+    """A ref holding its value, with a linked list of listeners: a listener
+    that unsubscribes and resubscribes itself while notified goes to the
+    front and is not called again."""
+
+    def __init__(self, value: A) -> None:
+        self.key = _new_key()
+        self._value = value
+        self._listeners: _Listener[A] | None = None
+
+    @property
+    def value(self) -> A:
+        return self._value
+
+    def notify(self, value: A) -> None:
+        listener = self._listeners
+        while listener is not None:
+            listener.f(value)
+            listener = listener.next
+
+    def subscribe(self, f: Callable[[A], None]) -> Callable[[], None]:
+        listener = _Listener(f, self._listeners)
+        if self._listeners is not None:
+            self._listeners.prev = listener
+        self._listeners = listener
+
+        def unsubscribe() -> None:
+            if self._listeners is listener:
+                self._listeners = listener.next
+            if listener.prev is not None:
+                listener.prev.next = listener.next
+            if listener.next is not None:
+                listener.next.prev = listener.prev
+
+        return unsubscribe
+
+
+class AtomRef[A](ReadonlyRef[A]):
+    """A ref that can be set."""
+
+    def set(self, value: A) -> Self:
+        raise NotImplementedError
+
+    def update(self, f: Callable[[A], A]) -> Self:
+        return self.set(f(self.value))
+
+    def prop(self, key: Any) -> AtomRef[Any]:
+        """A ref of one field of this ref's value; setting it sets this
+        ref to a copy with that field replaced."""
+        return _PropRef(self, key)
+
+
+class _ValueRef[A](_SourceRef[A], AtomRef[A]):
+    def __init__(self, value: A, on_notify: Callable[[A], None] | None = None) -> None:
+        super().__init__(value)
+        self._on_notify = on_notify
+
+    def set(self, value: A) -> Self:
+        if _equal.equals(value, self._value):
+            return self
+        self._value = value
+        self.notify(value)
+        if self._on_notify is not None:
+            self._on_notify(value)
+        return self
+
+
+class _MapRef[A, B](ReadonlyRef[B]):
+    def __init__(self, parent: ReadonlyRef[A], transform: Callable[[A], B]) -> None:
+        self.key = _new_key()
+        self._parent = parent
+        self._transform = transform
+
+    @property
+    def value(self) -> B:
+        return self._transform(self._parent.value)
+
+    def subscribe(self, f: Callable[[B], None]) -> Callable[[], None]:
+        previous = [self._transform(self._parent.value)]
+
+        def on_change(a: A) -> None:
+            next_value = self._transform(a)
+            if _equal.equals(next_value, previous[0]):
+                return
+            previous[0] = next_value
+            f(next_value)
+
+        return self._parent.subscribe(on_change)
+
+
+_ABSENT = object()
+
+
+def _field(value: object, key: Any) -> object:
+    if isinstance(value, Mapping):
+        return cast("Mapping[Any, Any]", value).get(key, _ABSENT)
+    if isinstance(value, list | tuple):
+        items = cast("list[Any] | tuple[Any, ...]", value)
+        return items[key] if isinstance(key, int) and -len(items) <= key < len(items) else _ABSENT
+    if dataclasses.is_dataclass(value) and isinstance(key, str):
+        return getattr(value, key, _ABSENT)
+    return _ABSENT
+
+
+def _replaced(value: object, key: Any, field: object) -> object:
+    if isinstance(value, list):
+        items = list(cast("list[Any]", value))
+        items[key] = field
+        return items
+    if isinstance(value, tuple):
+        items = list(cast("tuple[Any, ...]", value))
+        items[key] = field
+        return tuple(items)
+    if isinstance(value, Mapping):
+        return {**cast("Mapping[Any, Any]", value), key: field}
+    return dataclasses.replace(cast("Any", value), **{key: field})
+
+
+class _PropRef(AtomRef[Any]):
+    def __init__(self, parent: AtomRef[Any], key: Any) -> None:
+        self.key = _new_key()
+        self._parent = parent
+        self._prop = key
+        self._previous = _field(parent.value, key)
+
+    @property
+    def value(self) -> Any:
+        found = _field(self._parent.value, self._prop)
+        if found is not _ABSENT:
+            self._previous = found
+        return self._previous
+
+    def subscribe(self, f: Callable[[Any], None]) -> Callable[[], None]:
+        previous = [self.value]
+
+        def on_change(a: Any) -> None:
+            next_value = _field(a, self._prop)
+            if next_value is _ABSENT or _equal.equals(next_value, previous[0]):
+                return
+            previous[0] = next_value
+            f(next_value)
+
+        return self._parent.subscribe(on_change)
+
+    def set(self, value: Any) -> Self:
+        self._parent.set(_replaced(self._parent.value, self._prop, value))
+        return self
+
+    def update(self, f: Callable[[Any], Any]) -> Self:
+        current = _field(self._parent.value, self._prop)
+        return self.set(f(current))
+
+
+class Collection[A](_SourceRef[list[AtomRef[A]]]):
+    """A list of refs; changing one, or the list, notifies the collection."""
+
+    def __init__(self, items: Iterable[A]) -> None:
+        super().__init__([])
+        for item in items:
+            self._value.append(self._make_ref(item))
+
+    def _make_ref(self, value: A) -> AtomRef[A]:
+        return _ValueRef(value, lambda _: self.notify(self._value))
+
+    def push(self, item: A) -> Self:
+        self._value.append(self._make_ref(item))
+        self.notify(self._value)
+        return self
+
+    def insert_at(self, index: int, item: A) -> Self:
+        self._value.insert(index, self._make_ref(item))
+        self.notify(self._value)
+        return self
+
+    def remove(self, ref: AtomRef[A]) -> Self:
+        for index, candidate in enumerate(self._value):
+            if candidate is ref:
+                del self._value[index]
+                self.notify(self._value)
+                break
+        return self
+
+    def to_list(self) -> list[A]:
+        return [ref.value for ref in self._value]
+
+
+def make[A](value: A) -> AtomRef[A]:
+    """A ref holding ``value``."""
+    return _ValueRef(value)
+
+
+def collection[A](items: Iterable[A]) -> Collection[A]:
+    """A collection of refs of ``items``."""
+    return Collection(items)
+
+
+__all__ = ["AtomRef", "Collection", "ReadonlyRef", "collection", "make"]
+publish(globals())

pyfect/reactivity/atom_registry/__init__.py

@@ -0,0 +1,219 @@
+"""``AtomRegistry``: where atoms' values live (Effect's
+``effect/reactivity/AtomRegistry``).
+
+``make()`` creates a registry (``AtomRegistryService``); ``layer``
+provides one as the ``AtomRegistry`` service and disposes it with the
+layer's scope. ``r.get(atom)``, ``r.set(atom, value)``,
+``r.subscribe(atom, f)`` and ``r.mount(atom)`` work on it directly; the
+effect-returning ``to_stream``, ``get_result`` and ``mount`` take the
+registry as their first argument.
+
+A registry runs node removals, idle timeouts and the fibers of atoms
+backed by effects on one ``Scheduler``: the one given, else the running
+fiber's, else the running asyncio loop's.
+"""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from typing import TYPE_CHECKING, Any, Never, cast
+
+from pyfect._core import Effect, _Callback, _Sync, _WithFiber
+from pyfect._public import publish
+from pyfect.context import Tag
+from pyfect.duration import Duration
+from pyfect.layer import Layer
+from pyfect.layer import effect as layer_effect
+from pyfect.reactivity import async_result
+from pyfect.reactivity._result_effect import result_effect
+from pyfect.reactivity.async_result import AsyncResult, Initial
+from pyfect.reactivity.atom_registry._batch import batch
+from pyfect.reactivity.atom_registry._node import Node, NodeState
+from pyfect.reactivity.atom_registry._registry import (
+    AtomRegistryService,
+    InitialValue,
+    RegistryDisposedError,
+    RegistryThreadError,
+)
+from pyfect.scheduler import Scheduler
+from pyfect.scope import CloseableScope, Scope, acquire_release
+
+if TYPE_CHECKING:
+    from pyfect._fiber import Fiber
+    from pyfect.errors import Done
+    from pyfect.queue import Queue
+    from pyfect.reactivity.atom._types import Atom, AtomContext
+    from pyfect.stream import Stream
+
+
+class AtomRegistry(Tag[AtomRegistryService], key="~effect/reactivity/AtomRegistry"):
+    """The ``AtomRegistry`` service."""
+
+
+def is_atom_registry(u: object) -> bool:
+    return isinstance(u, AtomRegistryService)
+
+
+def make(
+    *,
+    initial_values: Iterable[InitialValue[Any]] | None = None,
+    scheduler: Scheduler | None = None,
+    timeout_resolution: Duration | None = None,
+    default_idle_ttl: Duration | None = None,
+) -> AtomRegistryService:
+    """A new registry. ``initial_values`` seed atoms (``atom.initial_value``);
+    ``default_idle_ttl`` keeps unused atoms that long, checked every
+    ``timeout_resolution`` (half the TTL by default, else a second).
+    Without ``scheduler`` it runs on the running fiber's scheduler, else
+    the running asyncio loop's (``NoRunError`` with neither)."""
+    return AtomRegistryService(
+        initial_values=initial_values,
+        scheduler=scheduler,
+        timeout_resolution=timeout_resolution,
+        default_idle_ttl=default_idle_ttl,
+    )
+
+
+def layer_options(
+    *,
+    initial_values: Iterable[InitialValue[Any]] | None = None,
+    scheduler: Scheduler | None = None,
+    timeout_resolution: Duration | None = None,
+    default_idle_ttl: Duration | None = None,
+) -> Layer[AtomRegistry]:
+    """A layer providing a registry made with these options (on the
+    building fiber's scheduler by default), disposed with its scope."""
+
+    def build(scope: CloseableScope) -> Effect[AtomRegistryService]:
+        def create() -> AtomRegistryService:
+            registry = make(
+                initial_values=initial_values,
+                scheduler=scheduler,
+                timeout_resolution=timeout_resolution,
+                default_idle_ttl=default_idle_ttl,
+            )
+            return registry
+
+        def register(registry: AtomRegistryService) -> Effect[AtomRegistryService]:
+            return scope.add_finalizer(lambda _exit: _Sync(registry.dispose)).as_(registry)
+
+        return _Sync(create).flat_map(register)
+
+    return layer_effect(AtomRegistry, Scope().flat_map(build))
+
+
+layer: Layer[AtomRegistry] = layer_options()
+"""Provides a registry with the default options."""
+
+
+# --- conversions ------------------------------------------------------------
+
+
+def to_stream[A](self: AtomRegistryService, atom: Atom[A]) -> Stream[A]:
+    """The atom's current value, then each new one."""
+    from pyfect import stream
+
+    def start(queue: Queue[A, Done]) -> Effect[None, Never, Scope]:
+        def offer(value: A) -> None:
+            queue.offer_unsafe(value)
+
+        def body(fiber: Fiber[Any, Any]) -> Effect[None]:
+            scope = fiber._context.get_unsafe(Scope)
+            cancel = self.subscribe(atom, offer, immediate=True)
+            return scope.add_finalizer(lambda _: _Sync(cancel))
+
+        return _WithFiber(body)
+
+    return stream.callback(start)
+
+
+def to_stream_result[A, E](
+    self: AtomRegistryService, atom: Atom[AsyncResult[A, E]]
+) -> Stream[A, E]:
+    """The values of an atom holding a result: initial results are skipped,
+    a failure fails the stream, and repeated values are dropped."""
+    return (
+        to_stream(self, atom)
+        .filter(async_result.is_not_initial)
+        .map_effect(result_effect)
+        .changes()
+    )
+
+
+def get_result[A, E](
+    self: AtomRegistryService,
+    atom: Atom[AsyncResult[A, E]],
+    *,
+    suspend_on_waiting: bool = False,
+) -> Effect[A, E]:
+    """The atom's success or failure, once it is not ``Initial`` (nor
+    waiting, with ``suspend_on_waiting``)."""
+
+    def ready(result: AsyncResult[A, E]) -> bool:
+        return not isinstance(result, Initial) and not (suspend_on_waiting and result.waiting)
+
+    def register(resume: Callable[[Effect[A, E]], None]) -> Effect[None] | None:
+        result = self.get(atom)
+        if ready(result):
+            resume(result_effect(result))
+            return None
+
+        def on_change(value: AsyncResult[A, E]) -> None:
+            if ready(value):
+                resume(result_effect(value))
+                cancel()
+
+        cancel = self.subscribe(atom, on_change)
+        return _Sync(cancel)
+
+    return _Callback(register)
+
+
+def mount(self: AtomRegistryService, atom: Atom[Any]) -> Effect[None, Never, Scope]:
+    """Keep ``atom`` mounted until the current scope closes."""
+    return acquire_release(_Sync(lambda: self.mount(atom)), lambda release, _: _Sync(release)).as_(
+        None
+    )
+
+
+def consume_skip_initial_run(ctx: AtomContext) -> bool:
+    """Whether this build keeps the node's seeded value instead of running
+    its effect (an ``initial_value`` with ``skip_initial_run``): once per
+    seed, and only while the parents it was seeded under are unchanged."""
+    from pyfect.reactivity.atom_registry._lifetime import Lifetime
+
+    lifetime = cast("Lifetime[Any]", ctx)
+    node = lifetime.node
+    if not node.skip_initial_run:
+        return False
+    kept = node.kept_parents
+    node.skip_initial_run = False
+    node.kept_parents = None
+    return (
+        not lifetime.is_fn
+        and not isinstance(node._value, Initial)
+        and (kept is None or all(parent.lifetime is life for parent, life in kept))
+    )
+
+
+__all__ = [
+    "AtomRegistry",
+    "AtomRegistryService",
+    "InitialValue",
+    "Node",
+    "NodeState",
+    "RegistryDisposedError",
+    "RegistryThreadError",
+    "batch",
+    "consume_skip_initial_run",
+    "get_result",
+    "is_atom_registry",
+    "layer",
+    "layer_options",
+    "make",
+    "mount",
+    "to_stream",
+    "to_stream_result",
+]
+publish(globals())

pyfect/reactivity/atom_registry/_batch.py

@@ -0,0 +1,96 @@
+"""Batching (Effect's ``AtomRegistry.batch``): inside ``batch(f)``, nodes
+that go stale are collected, and listeners hear of changes only once ``f``
+returns and the collected nodes are rebuilt.
+
+The batch state is per thread: a registry is used from the thread that
+runs its scheduler.
+"""
+
+from __future__ import annotations
+
+import threading
+from collections.abc import Callable, Iterable
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from pyfect.reactivity.atom_registry._node import Node
+
+DISABLED = 0
+COLLECT = 1
+COMMIT = 2
+
+
+class _BatchState(threading.local):
+    def __init__(self) -> None:
+        self.phase = DISABLED
+        self.depth = 0
+        self.stale: list[Node[Any]] = []
+        # An ordered set: the nodes whose listeners hear of the batch.
+        self.notify: dict[Node[Any], None] = {}
+
+
+state = _BatchState()
+
+
+class _NoFailure:
+    pass
+
+
+NO_FAILURE: object = _NoFailure()
+
+
+def run_all[T](items: Iterable[T], f: Callable[[T], None]) -> None:
+    """Run ``f`` for every item, then raise the first failure: one failing
+    step must not skip the others (they would leak a lifetime or miss an
+    update)."""
+    failure: BaseException | None = None
+    for item in items:
+        try:
+            f(item)
+        except Exception as error:
+            if failure is None:
+                failure = error
+    if failure is not None:
+        raise failure
+
+
+def batch(f: Callable[[], None]) -> None:
+    """Run ``f``; dependents of what it changes are rebuilt, and listeners
+    told, once it returns (also when it raises: what it changed is kept)."""
+    previous = state.phase
+    state.phase = COLLECT
+    state.depth += 1
+    failure: BaseException | None = None
+    try:
+        f()
+    except Exception as error:
+        failure = error
+    try:
+        if state.depth == 1:
+            stale, notify = state.stale, state.notify
+            i = 0
+            while True:
+                state.phase = COLLECT
+                while i < len(stale):
+                    try:
+                        stale[i].batch_rebuild()
+                    except Exception as error:
+                        failure = failure or error
+                    i += 1
+                state.phase = COMMIT
+                while notify:
+                    node = next(iter(notify))
+                    try:
+                        node.notify()
+                    except Exception as error:
+                        failure = failure or error
+                    notify.pop(node, None)
+                if i >= len(stale):
+                    break
+            state.stale = []
+            notify.clear()
+    finally:
+        state.depth -= 1
+        state.phase = previous
+    if failure is not None:
+        raise failure

pyfect/reactivity/atom_registry/_dispatcher.py

@@ -0,0 +1,60 @@
+"""Effect's per-fiber dispatcher flush for the fibers a registry forks.
+
+Effect runs an atom's effect with ``runForkWith`` and then flushes the
+fiber's dispatcher, so what the fiber yields (``yieldNow``, its step
+budget, a child it starts) runs before the build returns; only a real wait
+leaves the atom waiting. ``Dispatcher`` is the forked fiber's
+``CurrentScheduler``: inside ``run_flushed`` it queues what this thread
+schedules and runs it there, until nothing is left; otherwise it hands
+everything to the registry's scheduler.
+"""
+
+from __future__ import annotations
+
+import threading
+from collections import deque
+from collections.abc import Callable
+
+from pyfect._wake_tracking import WakeTracker
+from pyfect.duration import Seconds
+from pyfect.scheduler import Cancel, Scheduler, Task
+
+
+class Dispatcher:
+    __slots__ = ("_flushing", "_queue", "scheduler")
+
+    def __init__(self, scheduler: Scheduler) -> None:
+        self.scheduler = scheduler
+        self._queue: deque[Task] = deque()
+        self._flushing: int | None = None
+
+    def schedule(self, task: Task, priority: int = 0) -> None:
+        if self._flushing == threading.get_ident():
+            self._queue.append(task)
+        else:
+            self.scheduler.schedule(task)
+
+    def call_later(self, delay: Seconds, task: Task, *, daemon: bool = False) -> Cancel:
+        return self.scheduler.call_later(delay, task, daemon=daemon)
+
+    def track(self, tracker: WakeTracker, f: Callable[[], None]) -> None:
+        self.scheduler.track(tracker, f)
+
+    def outside_work(self) -> WakeTracker:
+        return self.scheduler.outside_work()
+
+    def run_flushed(self, start: Callable[[], None]) -> None:
+        """Run ``start``, then what it scheduled on this thread, until
+        nothing is left."""
+        outer = self._flushing
+        self._flushing = threading.get_ident()
+        try:
+            start()
+            while self._queue:
+                self._queue.popleft()()
+        finally:
+            self._flushing = outer
+            if outer is None:
+                # a task raised: the rest runs on the registry's scheduler
+                while self._queue:
+                    self.scheduler.schedule(self._queue.popleft())