Skip to main content

xrack_runtime/
loader.rs

1use crate::{Component, Node, Property, RowKey};
2use std::{
3    any::Any,
4    cell::{Cell, RefCell},
5    collections::VecDeque,
6    ops::Deref,
7    rc::{Rc, Weak},
8    sync::atomic::{AtomicU64, Ordering},
9    time::{Duration, Instant},
10};
11
12type BuildStep = Box<dyn FnOnce() -> Result<(), String>>;
13
14#[derive(Default)]
15struct BuildSteps {
16    children: VecDeque<BuildStep>,
17    complete: Vec<BuildStep>,
18}
19
20/// Construction jobs owned by one deferred Loader request.
21#[doc(hidden)]
22#[derive(Clone, Default)]
23pub struct LoaderBuild(Rc<RefCell<BuildSteps>>);
24
25thread_local! {
26    static CURRENT_BUILD: RefCell<Option<LoaderBuild>> = const { RefCell::new(None) };
27}
28
29impl LoaderBuild {
30    pub fn current() -> Option<Self> {
31        CURRENT_BUILD.with(|current| current.borrow().clone())
32    }
33
34    pub fn enqueue(&self, step: impl FnOnce() -> Result<(), String> + 'static) {
35        self.0.borrow_mut().children.push_back(Box::new(step));
36    }
37
38    pub fn complete(&self, step: impl FnOnce() -> Result<(), String> + 'static) {
39        self.0.borrow_mut().complete.push(Box::new(step));
40    }
41
42    fn scope<R>(&self, run: impl FnOnce() -> R) -> R {
43        struct Restore(Option<LoaderBuild>);
44        impl Drop for Restore {
45            fn drop(&mut self) {
46                CURRENT_BUILD.with(|current| current.replace(self.0.take()));
47            }
48        }
49        let _restore = Restore(CURRENT_BUILD.with(|current| current.replace(Some(self.clone()))));
50        run()
51    }
52
53    fn advance(&self, deadline: Option<Instant>, mut remaining: usize) -> Result<bool, String> {
54        loop {
55            let mut steps = self.0.borrow_mut();
56            if steps.children.is_empty() && steps.complete.is_empty() {
57                return Ok(true);
58            }
59            if deadline.is_some_and(|deadline| remaining == 0 || Instant::now() >= deadline) {
60                return Ok(false);
61            }
62            let step = steps.children.pop_front().or_else(|| steps.complete.pop());
63            drop(steps);
64            if let Some(step) = step {
65                self.scope(step)?;
66            }
67            remaining = remaining.saturating_sub(1);
68        }
69    }
70}
71
72/// Generated child storage. During a Loader build the child is filled by
73/// a construction job before the containing component is published.
74#[doc(hidden)]
75pub struct LoaderChild<T>(ChildStorage<T>);
76
77enum ChildStorage<T> {
78    Ready(T),
79    Pending(Rc<std::cell::OnceCell<T>>),
80}
81
82impl<T: 'static> LoaderChild<T> {
83    pub fn new(create: impl FnOnce() -> T + 'static) -> Self {
84        let Some(build) = LoaderBuild::current() else {
85            return Self(ChildStorage::Ready(create()));
86        };
87        let value = Rc::new(std::cell::OnceCell::new());
88        let target = Rc::downgrade(&value);
89        build.enqueue(move || {
90            if let Some(target) = target.upgrade() {
91                let _ = target.set(create());
92            }
93            Ok(())
94        });
95        Self(ChildStorage::Pending(value))
96    }
97}
98
99impl<T> Deref for LoaderChild<T> {
100    type Target = T;
101
102    #[expect(
103        clippy::expect_used,
104        reason = "a Loader publishes the component after all child jobs finish"
105    )]
106    fn deref(&self) -> &T {
107        match &self.0 {
108            ChildStorage::Ready(value) => value,
109            ChildStorage::Pending(value) => value.get().expect("component child initialized"),
110        }
111    }
112}
113
114#[derive(Default)]
115struct PendingBuild {
116    gate: Rc<Property<bool>>,
117    build: LoaderBuild,
118    started: bool,
119}
120
121impl PendingBuild {
122    fn waiting_scene(&self) -> Node {
123        LoaderFrame::waiting(&self.gate)
124    }
125}
126
127/// Stores the live candidate and the jobs required to finish a deferred candidate.
128#[doc(hidden)]
129#[derive(Default)]
130pub struct LoaderSlot {
131    instance: RefCell<Option<(usize, Rc<dyn Any>)>>,
132    pending: RefCell<Option<(usize, PendingBuild)>>,
133    mounted: Property<Option<usize>>,
134}
135
136impl LoaderSlot {
137    pub fn get<T: 'static>(&self, candidate: usize) -> Option<Rc<T>> {
138        if self.mounted.cached_value() != Some(Some(candidate)) {
139            return None;
140        }
141        self.storage(candidate)
142    }
143
144    fn storage<T: 'static>(&self, candidate: usize) -> Option<Rc<T>> {
145        let instance = self.instance.borrow();
146        let (current, value) = instance.as_ref()?;
147        if *current != candidate {
148            return None;
149        }
150        value.clone().downcast().ok()
151    }
152
153    #[doc(hidden)]
154    pub fn item<T: 'static>(
155        &self,
156        candidate: usize,
157        component: crate::WeakComponent<T>,
158    ) -> Option<LoaderItem<T>> {
159        if self.mounted.cached_value() != Some(Some(candidate)) {
160            return None;
161        }
162        let instance = self.instance.borrow();
163        let (current, storage) = instance.as_ref()?;
164        (*current == candidate).then(|| LoaderItem {
165            mount: Rc::downgrade(storage),
166            component,
167        })
168    }
169
170    pub fn is_mounted(&self, candidate: i64) -> bool {
171        self.mounted.get(|| None) == usize::try_from(candidate).ok() && candidate >= 0
172    }
173
174    pub fn render<T: Default + 'static>(
175        &self,
176        candidate: usize,
177        deferred: bool,
178        prepare: impl FnOnce(&T),
179        render: impl FnOnce(&T) -> Node,
180    ) -> Node {
181        self.try_render(
182            candidate,
183            deferred,
184            |value| Ok(prepare(value)),
185            |value| Ok(render(value)),
186            |error| panic!("generated component construction failed: {error}"),
187        )
188        .unwrap_or_else(|error: std::convert::Infallible| match error {})
189    }
190
191    pub fn try_render<T: Default + 'static, E>(
192        &self,
193        candidate: usize,
194        deferred: bool,
195        prepare: impl FnOnce(&T) -> Result<(), E>,
196        render: impl FnOnce(&T) -> Result<Node, E>,
197        build_error: impl FnOnce(String) -> E,
198    ) -> Result<Node, E> {
199        if let Some(value) = self.get::<T>(candidate) {
200            return render(&value);
201        }
202
203        let stored = self.storage::<T>(candidate);
204        if stored.is_none() {
205            self.instance.take();
206            self.mounted.set_if_changed(None);
207        }
208        let mut request = self
209            .pending
210            .take()
211            .and_then(|(key, build)| (key == candidate).then_some(build));
212        if deferred {
213            let pending = request.get_or_insert_with(PendingBuild::default);
214            if !pending.gate.get(|| false) {
215                let scene = pending.waiting_scene();
216                self.pending
217                    .replace(request.map(|build| (candidate, build)));
218                return Ok(scene);
219            }
220        }
221
222        let value = stored.unwrap_or_else(|| {
223            let value = Rc::new(T::default());
224            self.instance.replace(Some((candidate, value.clone())));
225            value
226        });
227        if let Some(mut pending) = request
228            && (deferred || pending.started)
229        {
230            const STEPS_PER_FRAME: usize = 8;
231            let deadline = deferred.then(|| Instant::now() + Duration::from_millis(2));
232            let mut remaining = STEPS_PER_FRAME;
233            if !pending.started {
234                if let Err(error) = pending.build.scope(|| prepare(&value)) {
235                    self.instance.take();
236                    return Err(error);
237                }
238                pending.started = true;
239                remaining -= 1;
240            }
241            match pending.build.advance(deadline, remaining) {
242                Ok(true) => {}
243                Ok(false) => {
244                    pending.gate = Rc::default();
245                    let scene = pending.waiting_scene();
246                    self.pending.replace(Some((candidate, pending)));
247                    return Ok(scene);
248                }
249                Err(error) => {
250                    self.instance.take();
251                    return Err(build_error(error));
252                }
253            }
254        }
255        let node = render(&value)?;
256        self.mounted.set_if_changed(Some(candidate));
257        Ok(node)
258    }
259
260    pub fn clear(&self, candidate: usize) {
261        if self
262            .instance
263            .borrow()
264            .as_ref()
265            .is_some_and(|(key, _)| *key == candidate)
266        {
267            self.instance.take();
268            self.mounted.set_if_changed(None);
269        }
270        if self
271            .pending
272            .borrow()
273            .as_ref()
274            .is_some_and(|(key, _)| *key == candidate)
275        {
276            self.pending.take();
277        }
278    }
279}
280
281/// A weak reference to a Loader candidate. Unmounting invalidates the handle.
282pub struct LoaderItem<T> {
283    mount: Weak<dyn Any>,
284    component: crate::WeakComponent<T>,
285}
286
287impl<T: 'static> LoaderItem<T> {
288    pub(crate) fn with_mount(mount: Weak<dyn Any>, component: crate::WeakComponent<T>) -> Self {
289        Self { mount, component }
290    }
291
292    /// Obtain the component while its original mount remains live.
293    pub fn upgrade(&self) -> Option<T> {
294        let _mount = self.mount.upgrade()?;
295        self.component.upgrade()
296    }
297
298    #[doc(hidden)]
299    pub fn cast<U: 'static>(self) -> Option<LoaderItem<U>> {
300        let component: Box<dyn Any> = Box::new(self.component);
301        Some(LoaderItem {
302            mount: self.mount,
303            component: *component.downcast::<crate::WeakComponent<U>>().ok()?,
304        })
305    }
306}
307
308impl<T> Clone for LoaderItem<T> {
309    fn clone(&self) -> Self {
310        Self {
311            mount: self.mount.clone(),
312            component: self.component.clone(),
313        }
314    }
315}
316
317/// A scene can release the pending request only while its Loader still owns it.
318#[doc(hidden)]
319#[derive(Clone, Debug)]
320pub struct LoaderFrame(Weak<Property<bool>>);
321
322impl LoaderFrame {
323    pub(crate) fn waiting(gate: &Rc<Property<bool>>) -> Node {
324        gate.get(|| false);
325        let mut node = Node::hidden();
326        node.set_loader_frame(Self(Rc::downgrade(gate)));
327        node
328    }
329}
330
331impl PartialEq for LoaderFrame {
332    fn eq(&self, other: &Self) -> bool {
333        self.0.ptr_eq(&other.0)
334    }
335}
336
337#[doc(hidden)]
338pub fn finish_loader_frame(scene: &Node) -> bool {
339    let mut advanced = false;
340    if let Some(gate) = scene
341        .loader_frame
342        .as_ref()
343        .and_then(|frame| frame.0.upgrade())
344        && gate.cached_value() != Some(true)
345    {
346        gate.set(true);
347        advanced = true;
348    }
349    for (_, child) in scene.materialized_children() {
350        advanced |= finish_loader_frame(child);
351    }
352    advanced
353}
354
355/// Identity and pending notification for an instance owned by a Loader.
356#[doc(hidden)]
357#[derive(Clone, Debug)]
358pub struct LoaderMount {
359    pending: Rc<Cell<bool>>,
360    pub(crate) key: RowKey,
361}
362
363impl Default for LoaderMount {
364    fn default() -> Self {
365        static NEXT_MOUNT: AtomicU64 = AtomicU64::new(1);
366        Self {
367            pending: Rc::new(Cell::new(true)),
368            key: RowKey {
369                model: 0,
370                row: NEXT_MOUNT.fetch_add(1, Ordering::Relaxed),
371                scope: 0,
372            },
373        }
374    }
375}
376
377impl PartialEq for LoaderMount {
378    fn eq(&self, other: &Self) -> bool {
379        self.key == other.key
380    }
381}
382
383/// Dispatch mount notifications from a committed scene. A handler can change
384/// the selected component, so let the host prepare a fresh scene on mutation.
385/// Returns whether the entire scene was visited.
386#[doc(hidden)]
387pub fn dispatch_loader_events(ui: &mut (impl Component + ?Sized), scene: &Node) -> bool {
388    fn walk(
389        ui: &mut (impl Component + ?Sized),
390        scene: &Node,
391        node: &Node,
392        path: &mut Vec<usize>,
393    ) -> bool {
394        if node.kind == "Loader"
395            && node
396                .children
397                .iter()
398                .find_map(|candidate| candidate.children.first()?.loader_mount.as_ref())
399                .is_some_and(|mount| mount.pending.replace(false))
400        {
401            ui.dispatch_at(scene, path, "loaded");
402            if ui.scene_dirty() {
403                return false;
404            }
405        }
406        if node.kind == "DynamicContainer" {
407            for child in &node.children {
408                if child
409                    .loader_mount
410                    .as_ref()
411                    .is_some_and(|mount| mount.pending.replace(false))
412                {
413                    ui.dispatch_at(scene, path, "mounted");
414                    if ui.scene_dirty() {
415                        return false;
416                    }
417                }
418            }
419        }
420        for (index, child) in node.materialized_children() {
421            path.push(index);
422            let visited = walk(ui, scene, child, path);
423            path.pop();
424            if !visited {
425                return false;
426            }
427        }
428        true
429    }
430    !ui.scene_dirty() && walk(ui, scene, scene, &mut Vec::new())
431}
432
433/// Keep the route to a Loader candidate while laying out its single child.
434#[doc(hidden)]
435pub fn loader_candidate_scene(children: Vec<Node>) -> Node {
436    if children.is_empty() {
437        return Node::hidden();
438    }
439    let mut node = Node::new("LoaderCandidate", None);
440    node.children = children;
441    node
442}
443
444#[cfg(test)]
445mod tests {
446    use super::*;
447
448    #[test]
449    fn switching_candidates_releases_previous_storage() {
450        let slot = LoaderSlot::default();
451        slot.render(0, false, |_: &usize| {}, |_: &usize| Node::hidden());
452        let previous = Rc::downgrade(&slot.get::<usize>(0).unwrap());
453
454        slot.render(
455            1,
456            false,
457            |_: &String| {},
458            |_: &String| {
459                assert!(previous.upgrade().is_none());
460                Node::hidden()
461            },
462        );
463        slot.clear(0);
464        assert!(slot.get::<String>(1).is_some());
465        slot.clear(1);
466        assert!(slot.get::<String>(1).is_none());
467    }
468
469    #[test]
470    fn cancel_releases_partial_storage_and_discards_remaining_jobs() {
471        let slot = LoaderSlot::default();
472        let partial = RefCell::new(Weak::new());
473        let advance = || {
474            slot.render(
475                0,
476                true,
477                |state: &RefCell<Option<Rc<()>>>| {
478                    let marker = Rc::new(());
479                    partial.replace(Rc::downgrade(&marker));
480                    state.replace(Some(marker));
481                    let build = LoaderBuild::current().unwrap();
482                    for _ in 0..32 {
483                        build.enqueue(|| Ok(()));
484                    }
485                },
486                |_| panic!("published partial candidate"),
487            )
488        };
489
490        let waiting = advance();
491        assert!(finish_loader_frame(&waiting));
492        let building = advance();
493        assert!(partial.borrow().upgrade().is_some());
494        assert!(!slot.is_mounted(0));
495        assert!(!finish_loader_frame(&waiting));
496        slot.clear(0);
497        assert!(partial.borrow().upgrade().is_none());
498        assert!(!finish_loader_frame(&building));
499    }
500
501    #[test]
502    fn superseded_frame_cannot_release_new_candidate() {
503        let slot = LoaderSlot::default();
504        let old = slot.render(0, true, |_: &usize| {}, |_: &usize| panic!("old mount"));
505        let new = slot.render(1, true, |_: &usize| {}, |_: &usize| panic!("early mount"));
506        assert!(!finish_loader_frame(&old));
507        assert!(!slot.is_mounted(1));
508        assert!(finish_loader_frame(&new));
509        assert!(!slot.is_mounted(1));
510        slot.render(1, true, |_: &usize| {}, |_: &usize| Node::hidden());
511        assert!(slot.is_mounted(1));
512    }
513}