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, and can't be sent to
16//! another thread.
17//! - `get()` and `with()` inside a memo or effect record a dependency.
18//! `get_untracked()`, `with_untracked()` and anything inside [`untrack`]
19//! don't. Dependencies are recorded afresh on every run.
20//! - `set()` and `update()` store the value, mark what read it as stale and
21//! queue effects. They never run anything; [`Runtime::flush`] does. If the
22//! closure passed to `update()` panics, readers are still told before the
23//! panic goes on. `try_set()` and `try_update()` return `false` on a
24//! disposed signal instead of panicking.
25//! - A memo recomputes only when read while stale. Its dependents rerun only
26//! if the new value differs from the old one. Memos must not write
27//! signals or call `flush()`: either panics, and the memo is disabled.
28//! - Reading a memo that has to recompute while one of its sources is being
29//! updated, or while a `with()` on the memo itself is running, panics in
30//! the reader. The memo is not disabled, and recomputes on its next read.
31//! - `flush()` runs queued effects in creation order, each at most once per
32//! round. Effects queued by writes during the flush run in a later round
33//! of the same flush. An effect queued again after running
34//! [`MAX_RUNS_PER_FLUSH`] times in one flush is logged and disabled.
35//! - Disposing an [`Owner`] frees everything created under it. After that,
36//! `get()` on its handles panics and `try_get()` returns `None`.
37//! [`Owner::effect_scoped`] gives each run of an effect a fresh scope
38//! owner and disposes the previous one. The last scope goes when the
39//! effect is disposed or disabled.
40//! - A memo or effect whose closure panics is logged and disabled, and the
41//! runtime stays usable. A panic in the `Drop` of a value or closure the
42//! runtime drops is logged too. Such `Drop` code records no dependencies.
43//! This needs `panic = "unwind"`, the default.
44//! - When the thread exits, the runtime is dropped with everything still in
45//! it. `Drop` code that calls back in then finds every handle disposed:
46//! `dispose()`, `set()` and `update()` do nothing, and `try_get()` returns
47//! `None`.
48//!
49//! # Example
50//!
51//! ```
52//! use std::cell::Cell;
53//! use std::rc::Rc;
54//!
55//! use crabshell_reactive::Runtime;
56//!
57//! let runtime = Runtime::current();
58//! let owner = runtime.new_owner(); // a widget opens one of these
59//!
60//! let count = owner.signal(1);
61//! let doubled = owner.memo(move || count.get() * 2);
62//! let shown = Rc::new(Cell::new(0));
63//! let sink = Rc::clone(&shown);
64//! owner.effect(move || sink.set(doubled.get())); // a binding is one of these
65//!
66//! runtime.flush(); // the event loop calls this once per iteration
67//! assert_eq!(shown.get(), 2);
68//!
69//! count.set(5); // queues the effect but runs nothing
70//! assert_eq!(shown.get(), 2);
71//! runtime.flush();
72//! assert_eq!(shown.get(), 10);
73//!
74//! owner.dispose(); // dropping the widget does this
75//! assert_eq!(count.try_get(), None);
76//! ```
77//!
78//! Handles stay on the thread that made them, so this doesn't compile:
79//!
80//! ```compile_fail,E0277
81//! let owner = crabshell_reactive::Runtime::current().new_owner();
82//! let count = owner.signal(0);
83//! std::thread::spawn(move || count.get());
84//! ```
85//!
86//! Handles are invariant in `T`, so subtyping can't turn a handle into one
87//! for a different type than the value it points to:
88//!
89//! ```compile_fail,E0308
90//! use crabshell_reactive::{Runtime, Signal};
91//!
92//! fn print_it(_: &str) {}
93//! let owner = Runtime::current().new_owner();
94//! let general: Signal<for<'a> fn(&'a str)> = owner.signal(print_it as for<'a> fn(&'a str));
95//! let narrowed: Signal<fn(&'static str)> = general;
96//! narrowed.try_get();
97//! ```
98
99#![forbid(unsafe_code)]
100#![warn(missing_docs)]
101
102mod effect;
103mod handle;
104mod memo;
105mod owner;
106mod runtime;
107mod signal;
108
109#[cfg(test)]
110mod tests;
111
112pub use effect::Effect;
113pub use memo::Memo;
114pub use owner::Owner;
115pub use runtime::{MAX_RUNS_PER_FLUSH, Runtime, untrack};
116pub use signal::{ReadSignal, Signal};