From 612b53af0a52090188db22d5442ff720346713b5 Mon Sep 17 00:00:00 2001 From: Craig Macomber Date: Thu, 15 May 2025 23:25:06 -0700 Subject: [PATCH 1/2] Clarify schedule_update docs --- packages/core/src/global_context.rs | 19 +++++++++++++------ packages/core/src/scope_context.rs | 13 ++++++++++--- 2 files changed, 23 insertions(+), 9 deletions(-) diff --git a/packages/core/src/global_context.rs b/packages/core/src/global_context.rs index da05b2d9f2..3f950bc2e7 100644 --- a/packages/core/src/global_context.rs +++ b/packages/core/src/global_context.rs @@ -310,34 +310,38 @@ pub fn use_hook(initializer: impl FnOnce() -> State) -> Runtime::with_current_scope(|cx| cx.use_hook(initializer)).unwrap() } -/// Get the current render since the inception of this component +/// Get the current render since the inception of this component. /// -/// This can be used as a helpful diagnostic when debugging hooks/renders, etc +/// This can be used as a helpful diagnostic when debugging hooks/renders, etc. pub fn generation() -> usize { Runtime::with_current_scope(|cx| cx.generation()).unwrap() } -/// Get the parent of the current scope if it exists +/// Get the parent of the current scope if it exists. pub fn parent_scope() -> Option { Runtime::with_current_scope(|cx| cx.parent_id()) .ok() .flatten() } -/// Mark the current scope as dirty, causing it to re-render +/// Mark the current scope as dirty, causing it to re-render. pub fn needs_update() { let _ = Runtime::with_current_scope(|cx| cx.needs_update()); } -/// Mark the current scope as dirty, causing it to re-render +/// Mark the current scope as dirty, causing it to re-render. pub fn needs_update_any(id: ScopeId) { let _ = Runtime::with_current_scope(|cx| cx.needs_update_any(id)); } -/// Schedule an update for the current component +/// Schedule an update for the current component. /// /// Note: Unlike [`needs_update`], the function returned by this method will work outside of the dioxus runtime. /// +/// Note: The function returned by this method will schedule an update for the current component even if it has already updated between when `schedule_update` was called and when the returned function is called. +/// If the desired behavior is to invalidate the current rendering of the current component (and on-op if already invalidated) +/// [`subscribe`](crate::reactive_context::ReactiveContext::subscribe) to the [`current`](crate::reactive_context::ReactiveContext::current) [`ReactiveContext`](crate::reactive_context::ReactiveContext) instead. +/// /// You should prefer [`schedule_update_any`] if you need to update multiple components. #[track_caller] pub fn schedule_update() -> Arc { @@ -349,6 +353,9 @@ pub fn schedule_update() -> Arc { /// A component's [`ScopeId`] can be obtained from the [`current_scope_id`] method. /// /// Note: Unlike [`needs_update`], the function returned by this method will work outside of the dioxus runtime. +/// +/// Note: The function returned by this method will schedule an update for the component even if it has already updated between when `schedule_update` was called and when the returned function is called. +/// If the desired behavior is to invalidate the current rendering of of the component (and op-op if already invalidated) use [`ReactiveContext`](crate::reactive_context::ReactiveContext) instead. #[track_caller] pub fn schedule_update_any() -> Arc { Runtime::with_current_scope(|cx| cx.schedule_update_any()).unwrap_or_else(|e| panic!("{}", e)) diff --git a/packages/core/src/scope_context.rs b/packages/core/src/scope_context.rs index d57b9706d1..ea690cc7a2 100644 --- a/packages/core/src/scope_context.rs +++ b/packages/core/src/scope_context.rs @@ -145,9 +145,13 @@ impl Scope { .expect("Scheduler to exist if scope exists"); } - /// Create a subscription that schedules a future render for the reference component + /// Create a subscription that schedules a future render for the referenced component. /// - /// ## Notice: you should prefer using [`Self::schedule_update_any`] and [`Self::scope_id`] + /// Note: you should prefer using [`Self::schedule_update_any`] and [`Self::scope_id`]. + /// + /// Note: The function returned by this method will schedule an update for the current component even if it has already updated between when `schedule_update` was called and when the returned function is called. + /// If the desired behavior is to invalidate the current rendering of the current component (and on-op if already invalidated) + /// [`subscribe`](crate::reactive_context::ReactiveContext::subscribe) to the [`current`](crate::reactive_context::ReactiveContext::current) [`ReactiveContext`](crate::reactive_context::ReactiveContext) instead. pub fn schedule_update(&self) -> Arc { let (chan, id) = (self.sender(), self.id); Arc::new(move || drop(chan.unbounded_send(SchedulerMsg::Immediate(id)))) @@ -157,7 +161,10 @@ impl Scope { /// /// A component's [`ScopeId`] can be obtained from `use_hook` or the [`current_scope_id`] method. /// - /// This method should be used when you want to schedule an update for a component + /// This method should be used when you want to schedule an update for a component. + /// + /// Note: The function returned by this method will schedule an update for the component even if it has already updated between when `schedule_update` was called and when the returned function is called. + /// If the desired behavior is to invalidate the current rendering of of the component (and op-op if already invalidated) use [`ReactiveContext`](crate::reactive_context::ReactiveContext) instead. pub fn schedule_update_any(&self) -> Arc { let chan = self.sender(); Arc::new(move |id| { From 50cea548f991b079b62cb0bf2b0684f2be545185 Mon Sep 17 00:00:00 2001 From: Craig Macomber Date: Fri, 16 May 2025 19:57:44 -0700 Subject: [PATCH 2/2] Fix typos and improve phrasing for schedule_update_any --- packages/core/src/global_context.rs | 6 +++--- packages/core/src/scope_context.rs | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/packages/core/src/global_context.rs b/packages/core/src/global_context.rs index 3f950bc2e7..451ac07a6c 100644 --- a/packages/core/src/global_context.rs +++ b/packages/core/src/global_context.rs @@ -339,7 +339,7 @@ pub fn needs_update_any(id: ScopeId) { /// Note: Unlike [`needs_update`], the function returned by this method will work outside of the dioxus runtime. /// /// Note: The function returned by this method will schedule an update for the current component even if it has already updated between when `schedule_update` was called and when the returned function is called. -/// If the desired behavior is to invalidate the current rendering of the current component (and on-op if already invalidated) +/// If the desired behavior is to invalidate the current rendering of the current component (and no-op if already invalidated) /// [`subscribe`](crate::reactive_context::ReactiveContext::subscribe) to the [`current`](crate::reactive_context::ReactiveContext::current) [`ReactiveContext`](crate::reactive_context::ReactiveContext) instead. /// /// You should prefer [`schedule_update_any`] if you need to update multiple components. @@ -354,8 +354,8 @@ pub fn schedule_update() -> Arc { /// /// Note: Unlike [`needs_update`], the function returned by this method will work outside of the dioxus runtime. /// -/// Note: The function returned by this method will schedule an update for the component even if it has already updated between when `schedule_update` was called and when the returned function is called. -/// If the desired behavior is to invalidate the current rendering of of the component (and op-op if already invalidated) use [`ReactiveContext`](crate::reactive_context::ReactiveContext) instead. +/// Note: It does not matter when `schedule_update_any` is called: the returned function will invalidate what ever generation of the specified component is current when returned function is called. +/// If the desired behavior is to schedule invalidation of the current rendering of a component, use [`ReactiveContext`](crate::reactive_context::ReactiveContext) instead. #[track_caller] pub fn schedule_update_any() -> Arc { Runtime::with_current_scope(|cx| cx.schedule_update_any()).unwrap_or_else(|e| panic!("{}", e)) diff --git a/packages/core/src/scope_context.rs b/packages/core/src/scope_context.rs index ea690cc7a2..6143ddd500 100644 --- a/packages/core/src/scope_context.rs +++ b/packages/core/src/scope_context.rs @@ -150,7 +150,7 @@ impl Scope { /// Note: you should prefer using [`Self::schedule_update_any`] and [`Self::scope_id`]. /// /// Note: The function returned by this method will schedule an update for the current component even if it has already updated between when `schedule_update` was called and when the returned function is called. - /// If the desired behavior is to invalidate the current rendering of the current component (and on-op if already invalidated) + /// If the desired behavior is to invalidate the current rendering of the current component (and no-op if already invalidated) /// [`subscribe`](crate::reactive_context::ReactiveContext::subscribe) to the [`current`](crate::reactive_context::ReactiveContext::current) [`ReactiveContext`](crate::reactive_context::ReactiveContext) instead. pub fn schedule_update(&self) -> Arc { let (chan, id) = (self.sender(), self.id); @@ -163,8 +163,8 @@ impl Scope { /// /// This method should be used when you want to schedule an update for a component. /// - /// Note: The function returned by this method will schedule an update for the component even if it has already updated between when `schedule_update` was called and when the returned function is called. - /// If the desired behavior is to invalidate the current rendering of of the component (and op-op if already invalidated) use [`ReactiveContext`](crate::reactive_context::ReactiveContext) instead. + /// Note: It does not matter when `schedule_update_any` is called: the returned function will invalidate what ever generation of the specified component is current when returned function is called. + /// If the desired behavior is to schedule invalidation of the current rendering of a component, use [`ReactiveContext`](crate::reactive_context::ReactiveContext) instead. pub fn schedule_update_any(&self) -> Arc { let chan = self.sender(); Arc::new(move |id| {