Docs

Author: MichaReiser

src/function.rs

@@ -275,7 +275,13 @@ where
             .unwrap_or(empty_cycle_heads())
     }
 
-    /// Attempts to claim `key_index`, returning `false` if a cycle occurs.
+    /// Attempts to claim `key_index` without blocking.
+    ///
+    /// * [`WaitForResult::Running`] if the `key_index` is running on another thread. It's up to the caller to block on the other thread
+    ///   to wait until the result becomes available.
+    /// * [`WaitForResult::Available`] It is (or at least was) possible to claim the `key_index`
+    /// * [`WaitResult::Cycle`] Claiming the `key_index` results in a cycle because it's on the current's thread query stack or
+    ///   running on another thread that is blocked on this thread.
     fn wait_for<'me>(&'me self, zalsa: &'me Zalsa, key_index: Id) -> WaitForResult<'me> {
         match self.sync_table.try_claim(zalsa, key_index) {
             ClaimResult::Running(blocked_on) => WaitForResult::Running(blocked_on),

src/function/memo.rs

@@ -366,14 +366,11 @@ impl<'a> TryClaimCycleHeadsIter<'a> {
     }
 
     fn queue_ingredient_heads(&mut self, ingredient: &dyn Ingredient, key: Id) {
-        // Recursively wait for all cycle heads that this head depends on.
-        // This is normally not necessary, because cycle heads are transitively added
-        // as query dependencies (they aggregate). The exception to this are queries
-        // that depend on a fixpoint initial value. They only depend on the fixpoint initial
-        // value but not on its dependencies because they aren't known yet. They're only known
-        // once the cycle completes but the cycle heads of the queries don't get updated.
-        // Because of that, recurse here to collect all cycle heads.
-        // This also ensures that if a query added new cycle heads, that they are awaited too.
+        // Recursively wait for all cycle heads that this head depends on. It's important
+        // that we fetch those from the updated memo because the cycle heads can change
+        // between iterations and new cycle heads can be added if a query depeonds on
+        // some cycle heads depending on a specific condition being met
+        // (`a` calls `b` and `c` in iteration 0 but `c` and `d` in iteration 1 or later).
         // IMPORTANT: It's critical that we get the cycle head from the latest memo
         // here, in case the memo has become part of another cycle (we need to block on that too!).
         self.queue.extend(

src/ingredient.rs

@@ -88,9 +88,13 @@ pub trait Ingredient: Any + std::fmt::Debug + Send + Sync {
     }
 
     /// Invoked when the current thread needs to wait for a result for the given `key_index`.
+    /// This call doesn't block the current thread. Instead, it's up to the caller to block
+    /// in case `key_index` is [running](`WaitForResult::Running`) on another thread.
     ///
-    /// A return value of `true` indicates that a result is now available. A return value of
-    /// `false` means that a cycle was encountered; the waited-on query is either already claimed
+    /// A return value of [`WaitForResult::Available`] indicates that a result is now available.
+    /// A return value of [`WaitForResult::Running`] indicates that `key_index` is currently running
+    /// on an other thread, it's up to caller to block until the result becomes available if desired.
+    /// A return value of [`WaitForResult::Cycle`] means that a cycle was encountered; the waited-on query is either already claimed
     /// by the current thread, or by a thread waiting on the current thread.
     fn wait_for<'me>(&'me self, zalsa: &'me Zalsa, key_index: Id) -> WaitForResult<'me> {
         _ = (zalsa, key_index);