Skip to main content

Crate crabshell_reactive

Crate crabshell_reactive 

Source
Expand description

Crabshell’s reactive core: a small single-threaded signal system.

TypeCreated withWhat it is
Signal<T>Owner::signalA value you set
ReadSignal<T>Signal::read_onlyA read-only view of a signal
Memo<T>Owner::memo, needs T: PartialEqA derived value, recomputed only when read while stale
EffectOwner::effect or Owner::effect_scopedCode that reruns when what it read changes

crabshell-ui’s Cx wraps an Owner, so widget code writes cx.signal(..), cx.memo(..) and cx.effect(..).

§How it behaves

  • Handles are Copy keys into this thread’s arena, and can’t be sent to another thread.
  • get() and with() inside a memo or effect record a dependency. get_untracked(), with_untracked() and anything inside untrack don’t. Dependencies are recorded afresh on every run.
  • set() and update() store the value, mark what read it as stale and queue effects. They never run anything; Runtime::flush does. If the closure passed to update() panics, readers are still told before the panic goes on. try_set() and try_update() return false on a disposed signal instead of panicking.
  • A memo recomputes only when read while stale. Its dependents rerun only if the new value differs from the old one. Memos must not write signals or call flush(): either panics, and the memo is disabled.
  • Reading a memo that has to recompute while one of its sources is being updated, or while a with() on the memo itself is running, panics in the reader. The memo is not disabled, and recomputes on its next read.
  • flush() runs queued effects in creation order, each at most once per round. Effects queued by writes during the flush run in a later round of the same flush. An effect queued again after running MAX_RUNS_PER_FLUSH times in one flush is logged and disabled.
  • Disposing an Owner frees everything created under it. After that, get() on its handles panics and try_get() returns None. Owner::effect_scoped gives each run of an effect a fresh scope owner and disposes the previous one. The last scope goes when the effect is disposed or disabled.
  • A memo or effect whose closure panics is logged and disabled, and the runtime stays usable. A panic in the Drop of a value or closure the runtime drops is logged too. Such Drop code records no dependencies. This needs panic = "unwind", the default.
  • When the thread exits, the runtime is dropped with everything still in it. Drop code that calls back in then finds every handle disposed: dispose(), set() and update() do nothing, and try_get() returns None.

§Example

use std::cell::Cell;
use std::rc::Rc;

use crabshell_reactive::Runtime;

let runtime = Runtime::current();
let owner = runtime.new_owner(); // a widget opens one of these

let count = owner.signal(1);
let doubled = owner.memo(move || count.get() * 2);
let shown = Rc::new(Cell::new(0));
let sink = Rc::clone(&shown);
owner.effect(move || sink.set(doubled.get())); // a binding is one of these

runtime.flush(); // the event loop calls this once per iteration
assert_eq!(shown.get(), 2);

count.set(5); // queues the effect but runs nothing
assert_eq!(shown.get(), 2);
runtime.flush();
assert_eq!(shown.get(), 10);

owner.dispose(); // dropping the widget does this
assert_eq!(count.try_get(), None);

Handles stay on the thread that made them, so this doesn’t compile:

ⓘ
let owner = crabshell_reactive::Runtime::current().new_owner();
let count = owner.signal(0);
std::thread::spawn(move || count.get());

Handles are invariant in T, so subtyping can’t turn a handle into one for a different type than the value it points to:

ⓘ
use crabshell_reactive::{Runtime, Signal};

fn print_it(_: &str) {}
let owner = Runtime::current().new_owner();
let general: Signal<for<'a> fn(&'a str)> = owner.signal(print_it as for<'a> fn(&'a str));
let narrowed: Signal<fn(&'static str)> = general;
narrowed.try_get();

Structs§

Effect
Code that reruns when what it read changes. Every widget binding is one.
Memo
A value derived from signals and other memos.
Owner
Owns every signal, memo, effect and child owner created through it, and frees them all when it is disposed.
ReadSignal
A read-only view of a Signal, made with Signal::read_only. Services hand these out so only they can change the value.
Runtime
This thread’s reactive runtime.
Signal
A value you set. A memo or effect that reads it reruns after it changes.

Constants§

MAX_RUNS_PER_FLUSH
How many times one effect may run in a single flush. An effect that is queued again after that is in a dependency cycle, so it is logged and disabled.

Functions§

untrack
Runs f without recording what it reads as dependencies of the running memo or effect, and returns f’s result. Recording resumes afterward, even if f panics.