wip: polish up some safety stuff and add suspense support in

packages/core/src/scope.rs

@@ -1,5 +1,5 @@
 use crate::innerlude::*;
-use fxhash::FxHashSet;
+use fxhash::{FxHashMap, FxHashSet};
 use std::{
     any::{Any, TypeId},
     cell::RefCell,
@@ -24,35 +24,116 @@ pub struct Scope {
     pub(crate) parent_idx: Option<ScopeId>,
     pub(crate) our_arena_idx: ScopeId,
     pub(crate) height: u32,
-    pub(crate) descendents: RefCell<FxHashSet<ScopeId>>,
 
     // Nodes
-    // an internal, highly efficient storage of vnodes
-    // lots of safety condsiderations
     pub(crate) frames: ActiveFrame,
     pub(crate) caller: *const dyn for<'b> Fn(&'b Scope) -> DomTree<'b>,
     pub(crate) child_nodes: ScopeChildren<'static>,
 
-    // Listeners
+    /*
+    we care about:
+    - listeners (and how to call them when an event is triggered)
+    - borrowed props (and how to drop them when the parent is dropped)
+    - suspended nodes (and how to call their callback when their associated tasks are complete)
+    */
     pub(crate) listeners: RefCell<Vec<*const Listener<'static>>>,
     pub(crate) borrowed_props: RefCell<Vec<*const VComponent<'static>>>,
-    pub(crate) suspended_nodes: RefCell<HashMap<u64, *const VSuspended<'static>>>,
+    pub(crate) suspended_nodes: RefCell<FxHashMap<u64, *const VSuspended<'static>>>,
 
     // State
     pub(crate) hooks: HookList,
     pub(crate) shared_contexts: RefCell<HashMap<TypeId, Rc<dyn Any>>>,
 
-    pub(crate) memoized_updater: Rc<dyn Fn() + 'static>,
+    // whenever set_state is called, we fire off a message to the scheduler
+    // this closure _is_ the method called by schedule_update that marks this component as dirty
+    pub(crate) memoized_updater: Rc<dyn Fn()>,
 
     pub(crate) shared: EventChannel,
 }
 
-// The type of closure that wraps calling components
+/// Public interface for Scopes.
+impl Scope {
+    /// Get the root VNode for this Scope.
+    ///
+    /// This VNode is the "entrypoint" VNode. If the component renders multiple nodes, then this VNode will be a fragment.
+    ///
+    /// # Example
+    /// ```rust
+    /// let mut dom = VirtualDom::new(|cx| cx.render(rsx!{ div {} }));
+    /// dom.rebuild();
+    ///
+    /// let base = dom.base_scope();
+    ///
+    /// if let VNode::VElement(node) = base.root_node() {
+    ///     assert_eq!(node.tag_name, "div");
+    /// }
+    /// ```
+    pub fn root_node(&self) -> &VNode {
+        self.frames.fin_head()
+    }
 
+    /// Get the height of this Scope - IE the number of scopes above it.
+    ///
+    /// A Scope with a height of `0` is the root scope - there are no other scopes above it.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// let mut dom = VirtualDom::new(|cx| cx.render(rsx!{ div {} }));
+    /// dom.rebuild();
+    ///
+    /// let base = dom.base_scope();
+    ///
+    /// assert_eq!(base.height(), 0);
+    /// ```
+    pub fn height(&self) -> u32 {
+        self.height
+    }
+
+    /// Get the Parent of this Scope within this Dioxus VirtualDOM.
+    ///
+    /// This ID is not unique across Dioxus VirtualDOMs or across time. IDs will be reused when components are unmounted.
+    ///
+    /// The base component will not have a parent, and will return `None`.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// let mut dom = VirtualDom::new(|cx| cx.render(rsx!{ div {} }));
+    /// dom.rebuild();
+    ///
+    /// let base = dom.base_scope();
+    ///
+    /// assert_eq!(base.parent(), None);
+    /// ```
+    pub fn parent(&self) -> Option<ScopeId> {
+        self.parent_idx
+    }
+
+    /// Get the ID of this Scope within this Dioxus VirtualDOM.
+    ///
+    /// This ID is not unique across Dioxus VirtualDOMs or across time. IDs will be reused when components are unmounted.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// let mut dom = VirtualDom::new(|cx| cx.render(rsx!{ div {} }));
+    /// dom.rebuild();
+    /// let base = dom.base_scope();
+    ///
+    /// assert_eq!(base.scope_id(), 0);
+    /// ```
+    pub fn scope_id(&self) -> ScopeId {
+        self.our_arena_idx
+    }
+}
+
+// The type of closure that wraps calling components
 /// The type of task that gets sent to the task scheduler
 /// Submitting a fiber task returns a handle to that task, which can be used to wake up suspended nodes
 pub type FiberTask = Pin<Box<dyn Future<Output = ScopeId>>>;
 
+/// Private interface for Scopes.
 impl Scope {
     // we are being created in the scope of an existing component (where the creator_node lifetime comes into play)
     // we are going to break this lifetime by force in order to save it on ourselves.
@@ -61,20 +142,23 @@ impl Scope {
     //
     // Scopes cannot be made anywhere else except for this file
     // Therefore, their lifetimes are connected exclusively to the virtual dom
-    pub(crate) fn new<'creator_node>(
-        caller: &'creator_node dyn for<'b> Fn(&'b Scope) -> DomTree<'b>,
-        arena_idx: ScopeId,
-        parent: Option<ScopeId>,
+    pub(crate) fn new(
+        caller: &dyn for<'b> Fn(&'b Scope) -> DomTree<'b>,
+        our_arena_idx: ScopeId,
+        parent_idx: Option<ScopeId>,
         height: u32,
         child_nodes: ScopeChildren,
         shared: EventChannel,
     ) -> Self {
         let child_nodes = unsafe { child_nodes.extend_lifetime() };
 
-        let up = shared.schedule_any_immediate.clone();
-        let memoized_updater = Rc::new(move || up(arena_idx));
+        let schedule_any_update = shared.schedule_any_immediate.clone();
+
+        let memoized_updater = Rc::new(move || schedule_any_update(our_arena_idx));
 
         let caller = caller as *const _;
+
+        // wipe away the associated lifetime - we are going to manually manage the one-way lifetime graph
         let caller = unsafe { std::mem::transmute(caller) };
 
         Self {
@@ -82,16 +166,16 @@ impl Scope {
             shared,
             child_nodes,
             caller,
-            parent_idx: parent,
-            our_arena_idx: arena_idx,
+            parent_idx,
+            our_arena_idx,
             height,
+
             frames: ActiveFrame::new(),
             hooks: Default::default(),
             suspended_nodes: Default::default(),
             shared_contexts: Default::default(),
             listeners: Default::default(),
             borrowed_props: Default::default(),
-            descendents: Default::default(),
         }
     }
 
@@ -107,35 +191,8 @@ impl Scope {
         self.child_nodes = child_nodes;
     }
 
-    /// Returns true if the scope completed successfully
-    ///
-    pub(crate) fn run_scope<'sel>(&'sel mut self, pool: &ResourcePool) -> bool {
-        // Cycle to the next frame and then reset it
-        // This breaks any latent references, invalidating every pointer referencing into it.
-        // Remove all the outdated listeners
-        self.ensure_drop_safety(pool);
-
-        // Safety:
-        // - We dropped the listeners, so no more &mut T can be used while these are held
-        // - All children nodes that rely on &mut T are replaced with a new reference
-        unsafe { self.hooks.reset() };
-
-        // Safety:
-        // - We've dropped all references to the wip bump frame
-        unsafe { self.frames.reset_wip_frame() };
-
-        // Cast the caller ptr from static to one with our own reference
-        let render: &dyn for<'b> Fn(&'b Scope) -> DomTree<'b> = unsafe { &*self.caller };
-
-        match render(self) {
-            None => false,
-            Some(new_head) => {
-                // the user's component succeeded. We can safely cycle to the next frame
-                self.frames.wip_frame_mut().head_node = unsafe { std::mem::transmute(new_head) };
-                self.frames.cycle_frame();
-                true
-            }
-        }
+    pub(crate) fn child_nodes<'a>(&'a self) -> ScopeChildren {
+        unsafe { self.child_nodes.shorten_lifetime() }
     }
 
     /// This method cleans up any references to data held within our hook list. This prevents mutable aliasing from
@@ -151,7 +208,6 @@ impl Scope {
         // make sure we drop all borrowed props manually to guarantee that their drop implementation is called before we
         // run the hooks (which hold an &mut Referrence)
         // right now, we don't drop
-        // let vdom = &self.vdom;
         self.borrowed_props
             .get_mut()
             .drain(..)
@@ -163,8 +219,8 @@ impl Scope {
                 scope.ensure_drop_safety(pool);
 
                 // Now, drop our own reference
-                let mut dropper = comp.drop_props.borrow_mut().take().unwrap();
-                dropper();
+                let mut drop_props = comp.drop_props.borrow_mut().take().unwrap();
+                drop_props();
             });
 
         // Now that all the references are gone, we can safely drop our own references in our listeners.
@@ -172,14 +228,10 @@ impl Scope {
             .get_mut()
             .drain(..)
             .map(|li| unsafe { &*li })
-            .for_each(|listener| {
-                listener.callback.borrow_mut().take();
-            });
+            .for_each(|listener| drop(listener.callback.borrow_mut().take()));
     }
 
-    // A safe wrapper around calling listeners
-    //
-    //
+    /// A safe wrapper around calling listeners
     pub(crate) fn call_listener(&mut self, event: SyntheticEvent, element: ElementId) {
         let listners = self.listeners.borrow_mut();
 
@@ -205,31 +257,68 @@ impl Scope {
         }
     }
 
-    pub(crate) fn child_nodes<'a>(&'a self) -> ScopeChildren {
-        unsafe { self.child_nodes.shorten_lifetime() }
-    }
+    /*
+    General strategy here is to load up the appropriate suspended task and then run it.
+    Suspended nodes cannot be called repeatedly.
+    */
+    pub(crate) fn call_suspended_node<'a>(&'a mut self, task_id: u64) {
+        let mut nodes = self.suspended_nodes.borrow_mut();
 
-    pub(crate) fn call_suspended_node<'a>(&'a self, task: u64) {
-        let g = self.suspended_nodes.borrow_mut();
-
-        if let Some(suspended) = g.get(&task) {
-            let sus: &'a VSuspended<'static> = unsafe { &**suspended };
+        if let Some(suspended) = nodes.remove(&task_id) {
+            let sus: &'a VSuspended<'static> = unsafe { &*suspended };
             let sus: &'a VSuspended<'a> = unsafe { std::mem::transmute(sus) };
 
-            let bump = self.frames.wip_frame();
-            let mut cb = sus.callback.borrow_mut();
-            let mut _cb = cb.take().unwrap();
             let cx: SuspendedContext<'a> = SuspendedContext {
                 inner: Context {
                     props: &(),
-                    scope: &self,
+                    scope: self,
                 },
             };
-            let new_node: DomTree<'a> = (_cb)(cx);
+
+            let mut cb = sus.callback.borrow_mut().take().unwrap();
+
+            let new_node: DomTree<'a> = (cb)(cx);
         }
     }
 
-    pub fn root(&self) -> &VNode {
-        self.frames.fin_head()
+    /// Render this component.
+    ///
+    /// Returns true if the scope completed successfully and false if running failed (IE a None error was propagated).
+    pub(crate) fn run_scope<'sel>(&'sel mut self, pool: &ResourcePool) -> bool {
+        // Cycle to the next frame and then reset it
+        // This breaks any latent references, invalidating every pointer referencing into it.
+        // Remove all the outdated listeners
+        self.ensure_drop_safety(pool);
+
+        // Safety:
+        // - We dropped the listeners, so no more &mut T can be used while these are held
+        // - All children nodes that rely on &mut T are replaced with a new reference
+        unsafe { self.hooks.reset() };
+
+        // Safety:
+        // - We've dropped all references to the wip bump frame
+        unsafe { self.frames.reset_wip_frame() };
+
+        // just forget about our suspended nodes while we're at it
+        self.suspended_nodes.get_mut().clear();
+
+        // guarantee that we haven't screwed up - there should be no latent references anywhere
+        debug_assert!(self.listeners.borrow().is_empty());
+        debug_assert!(self.suspended_nodes.borrow().is_empty());
+        debug_assert!(self.borrowed_props.borrow().is_empty());
+
+        // Cast the caller ptr from static to one with our own reference
+        let render: &dyn for<'b> Fn(&'b Scope) -> DomTree<'b> = unsafe { &*self.caller };
+
+        // Todo: see if we can add stronger guarantees around internal bookkeeping and failed component renders.
+        if let Some(new_head) = render(self) {
+            // the user's component succeeded. We can safely cycle to the next frame
+            self.frames.wip_frame_mut().head_node = unsafe { std::mem::transmute(new_head) };
+            self.frames.cycle_frame();
+
+            true
+        } else {
+            false
+        }
     }
 }