GitHub

API reference for Node.

class Node[A]

The registry's record of one atom.

Attributes

AttributeTypeDescription
registry= registry
atom= atom
state= UNINITIALIZED
lifetimeLifetime[A] | None = None
write_context= WriteContextImpl(registry, self)
preserve_initial_value_on_build= False
skip_initial_run= False
kept_parentslist[tuple[Node[Any], Lifetime[Any] | None]] | None = None
invalidated_during_build= False
failed= False
parentsdict[Node[Any], None] = {}
childrendict[Node[Any], None] = {}
listenersdict[_Listener, None] = {}
observed_children= 0
can_be_removedbool
buildingbool
is_observedbool

Functions

__init__

__init__(registry, atom) -> None
ParameterTypeDescription
registryAtomRegistryService
atomAtom[A]
def __init__(self, registry: AtomRegistryService, atom: Atom[A]) -> None:
    self.registry = registry
    self.atom = atom
    self.state = UNINITIALIZED
    self.lifetime: Lifetime[A] | None = None
    self.write_context = WriteContextImpl(registry, self)
    self.preserve_initial_value_on_build = False
    self.skip_initial_run = False
    # The parents, and their lifetimes, of a build that kept the seed
    # without reaching the effect (such as one waiting for a runtime).
    self.kept_parents: list[tuple[Node[Any], Lifetime[Any] | None]] | None = None
    self.invalidated_during_build = False
    self.failed = False
    # Every parent holding this node as a child. A stale node keeps the
    # parents of its last build, so they are not released and their next
    # change still reaches it; a build drops the parents it did not read.
    self.parents: dict[Node[Any], None] = {}
    self.children: dict[Node[Any], None] = {}
    self.listeners: dict[_Listener, None] = {}
    self.observed_children = 0
    self._value: A = None  # pyright: ignore[reportAttributeAccessIssue]

current_state

current_state() -> NodeState

Returns NodeState

def current_state(self) -> NodeState:
    match self.state:
        case 5:
            return "uninitialized"
        case 7:
            return "stale"
        case 3:
            return "valid"
        case _:
            return "removed"

child_observed

child_observed(delta) -> None
ParameterTypeDescription
deltaint
def child_observed(self, delta: int) -> None:
    observed = self.is_observed
    self.observed_children += delta
    if observed != self.is_observed:
        self.observed_changed(delta)

observed_changed

observed_changed(delta) -> None
ParameterTypeDescription
deltaint
def observed_changed(self, delta: int) -> None:
    for parent in list(self.parents):
        parent.child_observed(delta)

value

value() -> A

Returns A

def value(self) -> A:
    # A build can be superseded by a nested one, and that one go stale
    # again before the outer read returns.
    while self.state & WAITING_FOR_VALUE:
        self.build()
    return self._value

build

build() -> None
def build(self) -> None:
    from pyfect.reactivity.atom_registry._lifetime import Lifetime

    lifetime = Lifetime(self)
    # Release a failed or superseded build. Its finalizers run only once,
    # so their failure is raised once this build commits (Effect 4.1.2).
    try:
        self.dispose_lifetime()
    except Exception as error:
        lifetime.failure = error
    self.invalidated_during_build = False
    self.lifetime = lifetime
    read = False
    value: Any = None
    try:
        value = self.atom.read(lifetime)
        read = True
    finally:
        reads = lifetime.reads
        lifetime.reads = None
        if self.lifetime is lifetime:
            assert reads is not None
            self.drop_unread(reads)
            if not read:
                self.fail()
    if self.lifetime is lifetime and self.state & WAITING_FOR_VALUE:
        if self.preserve_initial_value_on_build:
            self.preserve_initial_value_on_build = False
            if self.skip_initial_run:
                self.kept_parents = [(parent, parent.lifetime) for parent in self.parents]
            self.failed = False
            self.state = VALID
        else:
            self.set_value(value)
    if lifetime.failure is not None:
        raise lifetime.failure

fail

fail() -> None

A build that raised leaves its dependents holding (or reading) a value this node no longer stands behind: they go stale and rebuild when pulled or observed. The read's error is the one reported.

def fail(self) -> None:
    """A build that raised leaves its dependents holding (or reading) a
    value this node no longer stands behind: they go stale and rebuild
    when pulled or observed. The read's error is the one reported."""
    self.failed = True
    # an observed dependent may rebuild and meet the same failure
    with contextlib.suppress(Exception):
        self.invalidate_children()

read_tracked

read_tracked[B](atom, lifetime) -> B
ParameterTypeDescription
atomAtom[B]
lifetimeLifetime[A]

Returns B

def read_tracked[B](self, atom: Atom[B], lifetime: Lifetime[A]) -> B:
    parent = self.registry.ensure_node(atom)
    # The dependency holds even when the parent cannot produce a value,
    # so that its recovery reaches this node; a build superseded while
    # the parent builds has the edge dropped by its replacement.
    if parent not in self.parents:
        self.parents[parent] = None
        parent.children[self] = None
        if self.is_observed:
            parent.child_observed(1)
    try:
        return parent.value()
    except Exception as error:
        # The parent may have got its value and failed only to update
        # another dependent: this build still takes the value, and
        # raises once it is done.
        if lifetime.reads is None or parent.state != VALID:
            raise
        if lifetime.failure is None:
            lifetime.failure = error
        return parent._value
    finally:
        # Read once the parent has answered: its commit while it is being
        # pulled is the value this build is about to receive.
        if lifetime.reads is not None and not lifetime.disposed:
            lifetime.reads[parent] = None

drop_unread

drop_unread(reads) -> None
ParameterTypeDescription
readsdict[Node[Any], None]
def drop_unread(self, reads: dict[Node[Any], None]) -> None:
    if len(reads) == len(self.parents):
        return
    observed = self.is_observed
    for parent in list(self.parents):
        if parent in reads:
            continue
        del self.parents[parent]
        parent.children.pop(self, None)
        if observed:
            parent.child_observed(-1)
        if parent.can_be_removed:
            self.registry.schedule_node_removal(parent)

value_option

value_option() -> Option[A]

Returns Option[A]

def value_option(self) -> Option[A]:
    if not self.state & INITIALIZED:
        return None
    return Some(self._value)

set_initial_value

set_initial_value(value, skip_initial_run=False) -> None
ParameterTypeDescription
valueA
skip_initial_runbool = False
def set_initial_value(self, value: A, skip_initial_run: bool = False) -> None:
    if not self.state & INITIALIZED:
        self.preserve_initial_value_on_build = True
        self.skip_initial_run = skip_initial_run
        self.state = STALE
        self._value = value
        if self.listeners:
            self.announce()
        return
    self.set_value(value)

release_hydrated_initial

release_hydrated_initial() -> None

Drop a hydrated Initial (kept through preserve_initial_value_on_build while unbuilt) so the atom computes its own value. A newer value is left alone.

def release_hydrated_initial(self) -> None:
    """Drop a hydrated ``Initial`` (kept through
    ``preserve_initial_value_on_build`` while unbuilt) so the atom
    computes its own value. A newer value is left alone."""
    if not isinstance(self._value, Initial):
        return
    self.preserve_initial_value_on_build = False
    self.invalidate()

set_value

set_value(value) -> None
ParameterTypeDescription
valueA
def set_value(self, value: A) -> None:
    # dependents that failed along with this node get another try
    recovered = self.failed
    self.failed = False
    initialized = bool(self.state & INITIALIZED)
    self.state = VALID
    if initialized and self.atom.equals(self._value, value):
        if recovered:
            self.invalidate_children()
        return
    self._value = value
    failure: Exception | None = None
    try:
        # A first value cannot replace one held by a dependent. Recovery
        # still retries dependents whose reads failed before this node
        # had a value.
        if initialized or recovered:
            self.invalidate_children()
    except Exception as error:
        failure = error
    # The value is committed, so its listeners hear of it even when a
    # dependent failed.
    if self.listeners:
        try:
            self.announce()
        except Exception as error:
            failure = failure or error
    if failure is not None:
        raise failure

announce

announce() -> None
def announce(self) -> None:
    if _batch.state.phase == _batch.COLLECT:
        _batch.state.notify[self] = None
    else:
        self.notify()

invalidate

invalidate() -> None
def invalidate(self) -> None:
    if self.state == VALID:
        self.state = STALE
        try:
            self.dispose_lifetime()
        finally:
            self.propagate()
    elif self.building and _batch.state.phase != _batch.COLLECT:
        # the running build read a parent that has changed since
        self.build()
    else:
        self.propagate()

propagate

propagate() -> None
def propagate(self) -> None:
    if _batch.state.phase == _batch.COLLECT:
        if self.building:
            self.invalidated_during_build = True
        _batch.state.stale.append(self)
    elif self.is_observed:
        self.value()
    else:
        self.invalidate_children()

invalidate_children

invalidate_children() -> None
def invalidate_children(self) -> None:
    if not self.children:
        return
    failure: Exception | None = None
    # a snapshot: a rebuild adds and drops children
    for child in list(self.children):
        if not child.affected_by(self):
            continue
        try:
            child.invalidate()
        except Exception as error:
            failure = failure or error
    if failure is not None:
        raise failure

affected_by

affected_by(parent) -> bool

Whether a change of parent reaches this node: it holds the parent's value, or a running build already read it. A stale node is stale already, and a build that has not read the parent yet will read the new value. The exception is an observed node that is still stale: its rebuild failed, and a parent that has a value again is its chance to recover.

ParameterTypeDescription
parentNode[Any]

Returns bool

def affected_by(self, parent: Node[Any]) -> bool:
    """Whether a change of ``parent`` reaches this node: it holds the
    parent's value, or a running build already read it. A stale node is
    stale already, and a build that has not read the parent yet will
    read the new value. The exception is an observed node that is still
    stale: its rebuild failed, and a parent that has a value again is its
    chance to recover."""
    if self.state == VALID:
        return True
    reads = None if self.lifetime is None else self.lifetime.reads
    if reads is not None:
        return parent in reads
    return self.is_observed and parent.state == VALID

notify

notify() -> None
def notify(self) -> None:
    if _batch.state.phase == _batch.COMMIT:
        _batch.state.notify.pop(self, None)
    run_all(live_keys(self.listeners), _call)

batch_rebuild

batch_rebuild() -> None
def batch_rebuild(self) -> None:
    if self.state == VALID:
        if not self.invalidated_during_build:
            return
        self.invalidated_during_build = False
        self.state = STALE
        self.dispose_lifetime()
    self.value()

dispose_lifetime

dispose_lifetime() -> None
def dispose_lifetime(self) -> None:
    lifetime = self.lifetime
    if lifetime is not None:
        self.lifetime = None
        lifetime.dispose()

remove

remove() -> None
def remove(self) -> None:
    observed = self.is_observed
    self.state = REMOVED
    self.listeners.clear()
    try:
        self.dispose_lifetime()
    finally:
        parents = list(self.parents)
        self.parents.clear()

        def release(parent: Node[Any]) -> None:
            parent.children.pop(self, None)
            if observed:
                parent.child_observed(-1)
            if parent.can_be_removed:
                self.registry.remove_node(parent)

        run_all(parents, release)

subscribe

subscribe(listener) -> Callable[[], None]

Add listener (called with no arguments on each change); returns the function that removes it.

ParameterTypeDescription
listenerCallable[[], None]

Returns Callable[[], None]

def subscribe(self, listener: Callable[[], None]) -> Callable[[], None]:
    """Add ``listener`` (called with no arguments on each change);
    returns the function that removes it."""
    observed = self.is_observed
    token = _Listener(listener)
    self.listeners[token] = None
    if not observed:
        self.observed_changed(1)

    def remove() -> None:
        if self.listeners.pop(token, _ABSENT) is not _ABSENT and not self.is_observed:
            self.observed_changed(-1)

    return remove