crabshell_reactive/owner.rs
1//! Owners: who frees which nodes.
2
3use std::marker::PhantomData;
4
5use crate::handle::{NotSend, handle_impls};
6use crate::runtime::{self, NodeId};
7use crate::{Effect, Memo, Signal};
8
9/// Owns every signal, memo, effect and child owner created through it, and
10/// frees them all when it is disposed.
11///
12/// Each widget opens one, and dropping the widget disposes it.
13/// `crabshell-ui`'s `Cx` wraps an `Owner`. Get a root owner from
14/// [`Runtime::new_owner`](crate::Runtime::new_owner) and nested ones from
15/// [`child`](Self::child).
16pub struct Owner {
17 id: NodeId,
18 _not_send: NotSend,
19}
20
21handle_impls!(Owner);
22
23impl Owner {
24 #[track_caller]
25 pub(crate) fn new(parent: Option<NodeId>) -> Self {
26 Owner {
27 id: runtime::create_owner(parent),
28 _not_send: PhantomData,
29 }
30 }
31
32 /// Creates an owner inside this one. Disposing this owner disposes the
33 /// child too.
34 ///
35 /// # Panics
36 ///
37 /// This and the other create methods panic if this owner was disposed.
38 #[track_caller]
39 pub fn child(&self) -> Owner {
40 Owner::new(Some(self.id))
41 }
42
43 /// Creates a [`Signal`] holding `value`.
44 #[track_caller]
45 pub fn signal<T: 'static>(&self, value: T) -> Signal<T> {
46 Signal::new(self.id, value)
47 }
48
49 /// Creates a [`Memo`] that derives its value with `f`. `f` first runs
50 /// when something reads the memo.
51 #[track_caller]
52 pub fn memo<T: PartialEq + 'static>(&self, f: impl FnMut() -> T + 'static) -> Memo<T> {
53 Memo::new(self.id, f)
54 }
55
56 /// Creates an [`Effect`] that runs `f` in the next flush round (see
57 /// [`Effect`]), and again whenever something `f` read changes.
58 #[track_caller]
59 pub fn effect(&self, f: impl FnMut() + 'static) -> Effect {
60 Effect::new(self.id, f)
61 }
62
63 /// Like [`effect`](Self::effect), for an effect that builds things on
64 /// every run, such as a list's child widgets.
65 ///
66 /// Each run gets a fresh owner, `scope`, to create them under. The scope
67 /// belongs to the effect itself: before the next run, the previous scope
68 /// is disposed with everything in it, and when the effect stops, its
69 /// last scope goes with it. The effect stops when this owner is
70 /// disposed, or when it is disabled after a panic or a dependency cycle.
71 #[track_caller]
72 pub fn effect_scoped(&self, mut f: impl FnMut(Owner) + 'static) -> Effect {
73 self.effect(move || {
74 f(Owner {
75 id: runtime::new_scope(),
76 _not_send: PhantomData,
77 });
78 })
79 }
80
81 /// Whether this owner was disposed, itself or with its parent, so
82 /// code that may outlive its context can check before it creates
83 /// anything under it, which would panic.
84 pub fn is_disposed(&self) -> bool {
85 runtime::is_disposed(self.id)
86 }
87
88 /// Frees this owner and everything created under it, child owners
89 /// included. Their values and closures are dropped and their effects
90 /// stop. Afterwards their handles' `get()` panics and `try_get()` returns
91 /// `None`. Disposing an owner twice does nothing.
92 pub fn dispose(self) {
93 runtime::dispose(self.id);
94 }
95
96 /// The owner's debug name, or its nearest named ancestor's, for log
97 /// lines about code that runs outside any node, such as a timer's.
98 /// `None` once disposed, or when nothing above it is named.
99 pub fn name(&self) -> Option<String> {
100 runtime::nearest_name(self.id)
101 }
102
103 /// Gives the owner a debug name, such as a widget path. Log lines about
104 /// its unnamed nodes mention it.
105 pub fn named(self, name: impl Into<String>) -> Self {
106 runtime::set_name(self.id, name.into());
107 self
108 }
109}