Expand description
Crabshell’s reactive core: a small single-threaded signal system.
| Type | Created with | What it is |
|---|---|---|
Signal<T> | Owner::signal | A value you set |
ReadSignal<T> | Signal::read_only | A read-only view of a signal |
Memo<T> | Owner::memo, needs T: PartialEq | A derived value, recomputed only when read while stale |
Effect | Owner::effect or Owner::effect_scoped | Code 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. get() inside a memo
or effect records a dependency; untrack and the _untracked methods
don’t. set() only marks readers stale and queues effects, and
Runtime::flush runs them. A memo recomputes when read while stale and
wakes its dependents only if its value changed. Disposing an Owner
frees everything created under it. A memo or effect that panics is logged
and disabled, and the runtime keeps working. The full rules are in the
design doc’s
Reactive core
section.
§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.
- Read
Signal - A read-only view of a
Signal, made withSignal::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
fwithout recording what it reads as dependencies of the running memo or effect, and returnsf’s result. Recording resumes afterward, even iffpanics.