Skip to main content

crabshell_reactive/
lib.rs

1//! Crabshell's reactive core: a small single-threaded signal system.
2//!
3//! | Type | Created with | What it is |
4//! |---|---|---|
5//! | [`Signal<T>`] | [`Owner::signal`] | A value you set |
6//! | [`ReadSignal<T>`] | [`Signal::read_only`] | A read-only view of a signal |
7//! | [`Memo<T>`] | [`Owner::memo`], needs `T: PartialEq` | A derived value, recomputed only when read while stale |
8//! | [`Effect`] | [`Owner::effect`] or [`Owner::effect_scoped`] | Code that reruns when what it read changes |
9//!
10//! `crabshell-ui`'s `Cx` wraps an [`Owner`], so widget code writes
11//! `cx.signal(..)`, `cx.memo(..)` and `cx.effect(..)`.
12//!
13//! # How it behaves
14//!
15//! Handles are `Copy` keys into this thread's arena. `get()` inside a memo
16//! or effect records a dependency; [`untrack`] and the `_untracked` methods
17//! don't. `set()` only marks readers stale and queues effects, and
18//! [`Runtime::flush`] runs them. A memo recomputes when read while stale and
19//! wakes its dependents only if its value changed. Disposing an [`Owner`]
20//! frees everything created under it. A memo or effect that panics is logged
21//! and disabled, and the runtime keeps working. The full rules are in the
22//! design doc's
23//! [Reactive core](https://github.com/w0x7y/crabshell/blob/main/docs/design.md#reactive-core)
24//! section.
25//!
26//! # Example
27//!
28//! ```
29//! use std::cell::Cell;
30//! use std::rc::Rc;
31//!
32//! use crabshell_reactive::Runtime;
33//!
34//! let runtime = Runtime::current();
35//! let owner = runtime.new_owner(); // a widget opens one of these
36//!
37//! let count = owner.signal(1);
38//! let doubled = owner.memo(move || count.get() * 2);
39//! let shown = Rc::new(Cell::new(0));
40//! let sink = Rc::clone(&shown);
41//! owner.effect(move || sink.set(doubled.get())); // a binding is one of these
42//!
43//! runtime.flush(); // the event loop calls this once per iteration
44//! assert_eq!(shown.get(), 2);
45//!
46//! count.set(5); // queues the effect but runs nothing
47//! assert_eq!(shown.get(), 2);
48//! runtime.flush();
49//! assert_eq!(shown.get(), 10);
50//!
51//! owner.dispose(); // dropping the widget does this
52//! assert_eq!(count.try_get(), None);
53//! ```
54//!
55//! Handles stay on the thread that made them, so this doesn't compile:
56//!
57//! ```compile_fail,E0277
58//! let owner = crabshell_reactive::Runtime::current().new_owner();
59//! let count = owner.signal(0);
60//! std::thread::spawn(move || count.get());
61//! ```
62//!
63//! Handles are invariant in `T`, so subtyping can't turn a handle into one
64//! for a different type than the value it points to:
65//!
66//! ```compile_fail,E0308
67//! use crabshell_reactive::{Runtime, Signal};
68//!
69//! fn print_it(_: &str) {}
70//! let owner = Runtime::current().new_owner();
71//! let general: Signal<for<'a> fn(&'a str)> = owner.signal(print_it as for<'a> fn(&'a str));
72//! let narrowed: Signal<fn(&'static str)> = general;
73//! narrowed.try_get();
74//! ```
75
76#![forbid(unsafe_code)]
77#![warn(missing_docs)]
78
79mod effect;
80mod handle;
81mod memo;
82mod owner;
83mod runtime;
84mod signal;
85
86#[cfg(test)]
87mod tests;
88
89pub use effect::Effect;
90pub use memo::Memo;
91pub use owner::Owner;
92pub use runtime::{MAX_RUNS_PER_FLUSH, Runtime, untrack};
93pub use signal::{ReadSignal, Signal};