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#[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#[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#[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
281pub 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 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#[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#[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#[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#[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}