pub struct TaskScope { /* private fields */ }Expand description
A node in the scope tree that owns spawned tasks and carries a typed context for dependency injection.
§Drop guarantee
When a TaskScope is dropped, all descendant scopes and their
tasks are cancelled iteratively using a work queue — recursion
is never used, so deeply nested UI trees (200+ levels) never
overflow the stack.
§Context
Use provide / consume
for lightweight dependency injection that walks up the scope tree.
§Callback lifecycle
CallbackHandles registered via
register_callback_handle are
dropped before spawned tasks are cancelled, ensuring that
signal subscriptions are removed before any task cleanup.
Implementations§
Source§impl TaskScope
impl TaskScope
Sourcepub fn new() -> Self
pub fn new() -> Self
Create a new root scope on the global thread-local executor.
For explicit executor ownership use TaskScope::with_executor.
Sourcepub fn with_executor(ex: &Rc<RefCell<Executor>>) -> Self
pub fn with_executor(ex: &Rc<RefCell<Executor>>) -> Self
Create a new root scope on the given executor.
All tasks spawned in this scope (and its descendants) run on
ex. The scope holds a strong reference, keeping the executor
alive at least as long as the scope.
Sourcepub fn new_child(parent: &Self) -> Self
pub fn new_child(parent: &Self) -> Self
Create a child scope that inherits the parent’s executor.
Sourcepub fn spawn(&self, future: impl Future<Output = ()> + 'static)
pub fn spawn(&self, future: impl Future<Output = ()> + 'static)
Spawn a future in this scope at low priority.
Sourcepub fn spawn_with_priority(
&self,
priority: Priority,
future: impl Future<Output = ()> + 'static,
)
pub fn spawn_with_priority( &self, priority: Priority, future: impl Future<Output = ()> + 'static, )
Spawn a future in this scope at the given priority.
The current scope is set to self during the spawn so that any
synchronous work inside the future constructor (e.g. bind_text)
can discover the owning scope via current_scope.
Sourcepub fn register_callback_handle(&self, handle: CallbackHandle)
pub fn register_callback_handle(&self, handle: CallbackHandle)
Register a CallbackHandle that will be dropped when this scope
is dropped (or when clear_callbacks is called).
Used by bind_* functions to ensure signal subscriptions are
cleaned up when the owning component is destroyed.
Sourcepub fn consume<T: 'static>(&self) -> Option<Rc<T>>
pub fn consume<T: 'static>(&self) -> Option<Rc<T>>
Look up a value of type T by walking up the scope tree.
Returns None if no ancestor (including self) has provided a
value of this type.
Sourcepub fn expect_context<T: 'static>(&self) -> Rc<T>
pub fn expect_context<T: 'static>(&self) -> Rc<T>
Sourcepub fn is_cancelled(&self) -> bool
pub fn is_cancelled(&self) -> bool
Return true if this scope has been cancelled (dropped).
A cancelled scope silently ignores spawn calls.
Sourcepub fn enter<R>(&self, f: impl FnOnce() -> R) -> R
pub fn enter<R>(&self, f: impl FnOnce() -> R) -> R
Run f with self set as the current scope for the thread.
Used by framework glue code so bind functions can discover the
owning scope via current_scope.
Sourcepub fn suspend(&self)
pub fn suspend(&self)
Suspend all tasks owned by this scope and its descendants.
Suspended tasks are skipped during executor polling. Signal
subscriptions remain registered but their callbacks are not
invoked while the scope is suspended. Use resume
to restart execution.
Used by if_async_cached and match_async_cached to pause
hidden branches.
Sourcepub fn resume(&self)
pub fn resume(&self)
Resume all tasks owned by this scope and its descendants.
This reverses the effect of suspend. Tasks
become eligible for polling again on the next executor flush.
Sourcepub fn is_suspended(&self) -> bool
pub fn is_suspended(&self) -> bool
Return true if this scope is currently suspended.