Skip to main content

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  /// Gives the owner a debug name, such as a widget path. Log lines about
97  /// its unnamed nodes mention it.
98  pub fn named(self, name: impl Into<String>) -> Self {
99    runtime::set_name(self.id, name.into());
100    self
101  }
102}