Skip to main content

xrack_runtime/
property.rs

1//! Lazy property bindings with dynamically tracked dependencies.
2use std::{
3    cell::{Cell, RefCell},
4    rc::{Rc, Weak},
5};
6
7thread_local! {
8    static EVALUATING: RefCell<Option<Rc<DependencyNode>>> = const { RefCell::new(None) };
9}
10
11#[derive(Default)]
12struct DependencyNode {
13    dirty: Cell<bool>,
14    evaluating: Cell<bool>,
15    sources: RefCell<Vec<Weak<Self>>>,
16    dependents: RefCell<Vec<Weak<Self>>>,
17}
18
19impl DependencyNode {
20    fn track(self: &Rc<Self>) {
21        EVALUATING.with(|current| {
22            let current = current.borrow();
23            let Some(binding) = current.as_ref() else {
24                return;
25            };
26            if Rc::ptr_eq(self, binding) {
27                return;
28            }
29            let mut sources = binding.sources.borrow_mut();
30            let source = Rc::downgrade(self);
31            if !sources.iter().any(|existing| existing.ptr_eq(&source)) {
32                sources.push(source);
33                self.dependents.borrow_mut().push(Rc::downgrade(binding));
34            }
35        });
36    }
37
38    fn detach(&self) {
39        let address = self as *const Self;
40        for source in self.sources.take() {
41            if let Some(source) = source.upgrade() {
42                source
43                    .dependents
44                    .borrow_mut()
45                    .retain(|binding| binding.as_ptr() != address);
46            }
47        }
48    }
49
50    fn push_dependents(&self, pending: &mut Vec<Rc<Self>>) {
51        self.dependents.borrow_mut().retain(|weak| {
52            if let Some(binding) = weak.upgrade() {
53                pending.push(binding);
54                true
55            } else {
56                false
57            }
58        });
59    }
60
61    fn notify(&self) {
62        let mut pending = Vec::new();
63        self.push_dependents(&mut pending);
64        while let Some(binding) = pending.pop() {
65            if !binding.dirty.replace(true) {
66                binding.push_dependents(&mut pending);
67            }
68        }
69    }
70
71    fn evaluate<T>(self: &Rc<Self>, binding: impl FnOnce() -> T) -> T {
72        self.detach();
73        self.evaluating.set(true);
74        self.dirty.set(false);
75        let mut evaluation = Evaluation {
76            node: self,
77            previous: EVALUATING.with(|current| current.replace(Some(self.clone()))),
78            completed: false,
79        };
80        let value = binding();
81        evaluation.completed = true;
82        value
83    }
84}
85
86impl Drop for DependencyNode {
87    fn drop(&mut self) {
88        self.detach();
89        self.notify();
90    }
91}
92
93struct Evaluation<'a> {
94    node: &'a DependencyNode,
95    previous: Option<Rc<DependencyNode>>,
96    completed: bool,
97}
98
99impl Drop for Evaluation<'_> {
100    fn drop(&mut self) {
101        EVALUATING.with(|current| current.replace(self.previous.take()));
102        self.node.evaluating.set(false);
103        if !self.completed && !self.node.dirty.replace(true) {
104            self.node.notify();
105        }
106    }
107}
108
109/// A dependency on mutable state that is stored outside a property.
110#[derive(Default)]
111pub struct ChangeSignal(Rc<DependencyNode>);
112
113impl ChangeSignal {
114    pub(crate) fn is_tracking() -> bool {
115        EVALUATING.with(|current| current.borrow().is_some())
116    }
117
118    pub(crate) fn has_dependents(&self) -> bool {
119        !self.0.dependents.borrow().is_empty()
120    }
121
122    pub fn track(&self) {
123        self.0.track();
124    }
125
126    pub fn notify(&self) {
127        self.0.notify();
128    }
129}
130
131enum Stored<T> {
132    Unset,
133    Explicit(T),
134    Cached(T),
135}
136
137/// Stores an explicit value or a lazily computed binding result.
138///
139/// The default closure supplied to `get` describes the same binding on each read.
140pub struct Property<T> {
141    value: RefCell<Stored<T>>,
142    binding: Option<Box<dyn Fn() -> T>>,
143    dependency: Rc<DependencyNode>,
144}
145
146impl<T> Default for Property<T> {
147    fn default() -> Self {
148        Self::new(None)
149    }
150}
151
152impl<T> Property<T> {
153    pub fn new(binding: Option<Box<dyn Fn() -> T>>) -> Self {
154        Self {
155            value: RefCell::new(Stored::Unset),
156            binding,
157            dependency: Rc::default(),
158        }
159    }
160
161    pub fn set(&self, value: T) {
162        self.replace(Stored::Explicit(value), true);
163    }
164
165    /// Inspect whether a cached binding needs reevaluation without tracking a read.
166    pub fn is_dirty(&self) -> bool {
167        self.dependency.dirty.get()
168    }
169
170    pub fn reset(&self) {
171        if matches!(*self.value.borrow(), Stored::Explicit(_)) {
172            self.replace(Stored::Unset, true);
173        }
174    }
175
176    fn replace(&self, value: Stored<T>, changed: bool) {
177        let previous = self.value.replace(value);
178        self.dependency.detach();
179        self.dependency.dirty.set(true);
180        if changed {
181            self.dependency.notify();
182        }
183        drop(previous);
184    }
185}
186
187impl<T: PartialEq> Property<T> {
188    /// Override the binding and invalidate dependents only when its known value changes.
189    pub fn set_if_changed(&self, value: T) {
190        let changed = match &*self.value.borrow() {
191            Stored::Explicit(current) => {
192                if *current == value {
193                    return;
194                }
195                true
196            }
197            Stored::Cached(current) if !self.dependency.dirty.get() => *current != value,
198            Stored::Unset | Stored::Cached(_) => true,
199        };
200        self.replace(Stored::Explicit(value), changed);
201    }
202}
203
204impl<T: Clone> Property<T> {
205    /// Observe an explicit override while leaving the default to the caller.
206    pub fn explicit_value(&self) -> Option<T> {
207        self.dependency.track();
208        match &*self.value.borrow() {
209            Stored::Explicit(value) => Some(value.clone()),
210            _ => None,
211        }
212    }
213
214    pub fn get(&self, default: impl FnOnce() -> T) -> T {
215        assert!(
216            !self.dependency.evaluating.get(),
217            "cyclic property evaluation"
218        );
219        self.dependency.track();
220        match &*self.value.borrow() {
221            Stored::Explicit(value) => return value.clone(),
222            Stored::Cached(value) if !self.dependency.dirty.get() => return value.clone(),
223            Stored::Unset | Stored::Cached(_) => {}
224        }
225
226        let value = self.dependency.evaluate(|| match &self.binding {
227            Some(binding) => binding(),
228            None => default(),
229        });
230        if !self.dependency.dirty.get() {
231            let cached = value.clone();
232            if !self.dependency.dirty.get() {
233                self.value.replace(Stored::Cached(cached));
234            }
235        }
236        value
237    }
238}
239
240/// Storage for a generated component input. Linked inputs track the actual
241/// source property and forward writes without allocating a second value slot.
242#[doc(hidden)]
243pub enum InputProperty<T> {
244    Local(Property<T>),
245    Linked {
246        read: Box<dyn Fn() -> Option<T>>,
247        write: Box<dyn Fn(T)>,
248    },
249    State {
250        value: Property<T>,
251        read: Box<dyn Fn() -> Option<T>>,
252        base: Box<Self>,
253    },
254}
255
256impl<T> Default for InputProperty<T> {
257    fn default() -> Self {
258        Self::Local(Property::default())
259    }
260}
261
262impl<T> InputProperty<T> {
263    pub fn bound(read: impl Fn() -> T + 'static) -> Self {
264        Self::Local(Property::new(Some(Box::new(read))))
265    }
266
267    pub fn linked(read: impl Fn() -> Option<T> + 'static, write: impl Fn(T) + 'static) -> Self {
268        Self::Linked {
269            read: Box::new(read),
270            write: Box::new(write),
271        }
272    }
273
274    /// Add a lazy state binding above an existing input. An explicit write
275    /// replaces this binding until reset, including when the value is equal.
276    pub fn with_state(self, read: impl Fn() -> Option<T> + 'static) -> Self {
277        Self::State {
278            value: Property::default(),
279            read: Box::new(read),
280            base: Box::new(self),
281        }
282    }
283
284    pub fn reset(&self) {
285        match self {
286            Self::Local(value) | Self::State { value, .. } => value.reset(),
287            Self::Linked { .. } => {}
288        }
289    }
290}
291
292impl<T: Clone> InputProperty<T> {
293    pub fn get(&self, default: impl FnOnce() -> T) -> T {
294        match self {
295            Self::Local(property) => property.get(default),
296            Self::Linked { read, .. } => read().unwrap_or_else(default),
297            Self::State { value, read, base } => {
298                value.get(|| read().unwrap_or_else(|| base.get(default)))
299            }
300        }
301    }
302}
303
304impl<T: PartialEq> InputProperty<T> {
305    pub fn set_if_changed(&self, value: T) {
306        match self {
307            Self::Local(property)
308            | Self::State {
309                value: property, ..
310            } => property.set_if_changed(value),
311            Self::Linked { write, .. } => write(value),
312        }
313    }
314}
315
316#[cfg(test)]
317mod tests {
318    use super::*;
319    use std::panic::{AssertUnwindSafe, catch_unwind};
320
321    #[test]
322    fn state_input_restores_the_live_fallback_after_reset() {
323        let active = Rc::new(Property::default());
324        active.set(true);
325        let base = Property::default();
326        base.set(1);
327        let state = active.clone();
328        let input = InputProperty::default().with_state(move || state.get(|| false).then_some(2));
329        let read = || input.get(|| base.get(|| 0));
330
331        assert_eq!(read(), 2);
332        input.set_if_changed(2);
333        active.set(false);
334        base.set(3);
335        assert_eq!(read(), 2);
336        input.reset();
337        assert_eq!(read(), 3);
338        active.set(true);
339        assert_eq!(read(), 2);
340    }
341
342    #[test]
343    fn invalidation_reaches_a_diamond_once() {
344        let source = Property::default();
345        let left = Property::default();
346        let right = Property::default();
347        let total = Property::default();
348        let evaluations = Cell::new(0);
349
350        source.set(1);
351        let value = || {
352            total.get(|| {
353                evaluations.set(evaluations.get() + 1);
354                let left = left.get(|| source.get(|| 0) + source.get(|| 0));
355                left + right.get(|| source.get(|| 0) * 3)
356            })
357        };
358        assert_eq!(value(), 5);
359        source.set(2);
360        source.set(3);
361        assert_eq!(evaluations.get(), 1);
362        assert_eq!(value(), 15);
363        assert_eq!(value(), 15);
364        assert_eq!(evaluations.get(), 2);
365    }
366
367    #[test]
368    fn unwinding_a_nested_evaluation_allows_retry_and_restores_tracking() {
369        let source = Property::default();
370        let inner = Property::default();
371        let outer = Property::default();
372        let first = Cell::new(true);
373        source.set(7);
374
375        let value = || {
376            outer.get(|| {
377                catch_unwind(AssertUnwindSafe(|| {
378                    inner.get(|| {
379                        let number = source.get(|| 0);
380                        assert!(!first.replace(false), "transient failure");
381                        number
382                    })
383                }))
384                .unwrap_or(0)
385            })
386        };
387        assert_eq!(value(), 0);
388        assert_eq!(value(), 7);
389        source.set(9);
390        assert_eq!(value(), 9);
391    }
392
393    #[test]
394    fn invalidation_during_evaluation_does_not_cache_an_obsolete_result() {
395        let source = Property::default();
396        let derived = Property::default();
397        source.set(1);
398
399        assert_eq!(
400            derived.get(|| {
401                let previous = source.get(|| 0);
402                source.set(2);
403                previous
404            }),
405            1
406        );
407        assert_eq!(derived.get(|| source.get(|| 0)), 2);
408        assert_eq!(derived.get(|| panic!("cache should be valid")), 2);
409    }
410
411    #[test]
412    fn dropping_a_source_invalidates_bindings_that_read_through_weak_references() {
413        let source = Rc::new(Property::default());
414        source.set(8);
415        let weak = Rc::downgrade(&source);
416        let derived = Property::default();
417        let value = || derived.get(|| weak.upgrade().map_or(0, |source| source.get(|| 0)));
418        assert_eq!(value(), 8);
419        drop(source);
420        assert_eq!(value(), 0);
421    }
422}