subtle: primitives for framework authors¶
reaktiv.subtle contains low-level building blocks modelled on the TC39
Signal.subtle namespace. Application code should use effect; reach for these
when you integrate reaktiv into a framework, UI loop or host that owns scheduling.
Custom scheduling with Watcher¶
effect runs synchronously when the outermost batch ends. A Watcher lets you
choose when work runs instead. It is notified when a watched signal may have
changed, before anything is recomputed, and you evaluate on your own schedule:
import asyncio
from reaktiv import computed, signal
from reaktiv.subtle import Watcher
async def main() -> None:
count = signal(1)
label = computed(lambda: f"count={count()}")
loop = asyncio.get_running_loop()
def flush() -> None:
watcher.watch() # re-arm first (see below)
for node in watcher.get_pending():
print(node()) # evaluate, then commit side effects here
watcher = Watcher(lambda: loop.call_soon(flush))
watcher.watch(label)
flush() # prints "count=1"
count.set(2) # notify only; nothing is recomputed yet
await asyncio.sleep(0) # flush runs on the next tick: prints "count=2"
asyncio.run(main())
Rules:
notifyruns synchronously during propagation, also insidebatch, and at most once untilwatch()re-arms the watcher. Reading or writing any signal innotifyraises, also throughuntracked, and a rejected read evaluates nothing. Work thatnotifyschedules (call_soon,create_task, a queue) runs later and can read and write normally.- Re-arm at the start of your flush, before reading pending nodes. If committing a result changes a watched dependency, the armed watcher notifies again and the next flush picks up the new value. Re-arming at the end would suppress that notification and leave work pending with no flush scheduled. A commit that always changes its own inputs therefore reschedules forever, one flush at a time.
watch(*nodes)andunwatch(*nodes)never evaluate. Watching a computed keeps it subscribed to its sources; unwatching releases that subscription.get_pending()returns watched computed nodes that need evaluation, as the same handles you passed in (read-only wrappers stay read-only). Plain signals notify but are never pending.- Computations cannot write signals. Put side effects in your flush, after reading the pending nodes.
- Like effects, a watcher is referenced weakly by its sources. Keep a reference
for as long as it should observe, then call
dispose()(or register it withmodel.own). After disposalnotifynever runs andwatch()does nothing, so a flush scheduled before disposal can still re-arm safely.
Differences from TC39 Signal.subtle¶
Watcher follows the TC39 proposal's contract ("may have changed", no reads or
writes during notify, re-arm with watch()), with these deliberate differences:
- Weak retention. Sources reference a watcher weakly, as they do effects. A watcher you don't keep a reference to is garbage collected and stops observing. In TC39, watched signals keep their watcher alive.
- Exceptions in
notifyare printed, not raised. The change keeps reaching the remaining effects and watchers, so one faulty callback cannot leave the graph half-notified. dispose()stops a watcher permanently; TC39 has onlyunwatch.- No graph introspection. There is no
introspectSources/introspectSinksand nowatched/unwatchedcallbacks.current_consumer()andsignal_version()are not a substitute for dependency inspection; public graph traversal for tooling is a separate API decision.
Read tracking and change detection¶
current_consumer()returns the computation or effect currently tracking reads, orNone(also insideuntrackedand duringnotify). Treat it as an opaque identity.signal_version(node)returns a node's revision without reading, evaluating or tracking it. It advances when the node publishes a new value or error, is local to that node, and a stale computed keeps its old revision until read.
Owning extension objects¶
model.own(value) registers an object with a ReactiveModel and returns it.
The object must implement dispose() or destroy(); otherwise TypeError is
raised. model.dispose() cleans up owned objects in reverse registration order,
once each.
reaktiv.subtle.Watcher
¶
Get notified when watched signals may have changed, without evaluating them.
notify runs synchronously while a change propagates (also inside
batch), at most once until the watcher is re-armed with watch().
It must not read or write signals, not even through untracked; doing
so raises. Schedule work instead, and read the nodes returned by
get_pending() on your own schedule::
watcher = Watcher(lambda: loop.call_soon(flush))
view = computed(render)
watcher.watch(view)
def flush():
watcher.watch() # re-arm first, so changes made while
# committing schedule another flush
for node in watcher.get_pending():
commit(node()) # evaluate and apply side effects here
Re-arming after committing instead would suppress notifications caused by the commit and leave nodes pending with no flush scheduled.
Differences from TC39 Signal.subtle.Watcher: sources reference a
watcher weakly (keep it alive for as long as it should observe, and call
dispose() or register it with model.own when finished); exceptions
raised by notify are printed instead of propagating, so the remaining
consumers are still notified. As in TC39, only computed nodes are ever
pending; watching a plain signal notifies but never makes it pending.
watch(*nodes)
¶
Start watching nodes and re-arm notify. Never evaluates them.
Does nothing after dispose(), so an already scheduled flush can
safely re-arm a watcher that was disposed in the meantime.
unwatch(*nodes)
¶
Stop watching nodes; nodes that are not watched are ignored.
dispose()
¶
Stop watching everything; notify is never called again.
get_pending()
¶
Return watched computed nodes that need evaluation. Never evaluates.
reaktiv.subtle.current_consumer()
¶
Return the computation or effect currently tracking reads, or None.
None also inside untracked and during a Watcher's notify. Treat
the result as an opaque identity:
do not run, schedule or mutate it.
reaktiv.subtle.signal_version(node)
¶
Return the node's revision without reading, evaluating or tracking it.
The revision advances whenever the node publishes a new value (or error). It is local to one node. A computed that is stale keeps its old revision until something reads it.