Struct TaskScope 

pub struct TaskScope { /* private fields */ }

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.

Cancellation is cooperative

Cancellation drops the task’s Future and removes it from the executor. Like all async Rust, this only takes effect at the next .await point — a task stuck in a synchronous compute loop cannot be interrupted mid-execution. This is the same trade-off made by tokio::task::JoinHandle::abort. For long synchronous work, insert yield_now at checkpoints.

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

impl TaskScope

pub fn new() -> Self

Create a new root scope on the global thread-local executor.

For explicit executor ownership use TaskScope::with_executor.

Examples found in repository

examples/counter.rs (line 65)

fn main() {
    // One-time executor setup.
    init_flush_scheduler(Rc::new(CliScheduler));
    init_time_source(Rc::new(CliClock::new()));

    // ---- Signal basics ----
    println!("=== Signal basics ===");
    let count = Signal::new(0);
    println!("count = {}", count.read());
    count.set(42);
    println!("count = {}", count.read());

    // ---- Memo (auto-tracking computed value) ----
    println!("\n=== Memo ===");
    let a = Signal::new(2);
    let b = Signal::new(3);
    let a2 = a.clone();
    let b2 = b.clone();
    let sum = Memo::new(move || a2.read() + b2.read());
    println!("2 + 3 = {}", sum.read());
    a.set(10);
    println!("10 + 3 = {}", sum.read());

    // ---- TaskScope: spawn a task that watches a signal ----
    println!("\n=== TaskScope (scoped signal watcher) ===");
    let messages = Signal::new(vec!["hello".to_string()]);

    {
        let scope = TaskScope::new();
        let msgs = messages.clone();
        scope.spawn(async move {
            loop {
                let val = msgs.changed().await;
                println!("  task observed: {:?}", val);
            }
        });

        messages.set(vec!["hello".to_string(), "world".to_string()]);
        messages.set(vec![
            "hello".to_string(),
            "world".to_string(),
            "!".to_string(),
        ]);

        // Explicit drop — cancels the task and cleans up resources.
        drop(scope);
    }
    println!("(scope dropped — task and subscriptions cleaned up)");

    // ---- Batch: multiple sets, one notification ----
    println!("\n=== Batch ===");
    let x = Signal::new(0);
    let notifications = Rc::new(Cell::new(0u32));
    let n = Rc::clone(&notifications);
    let x2 = x.clone();

    let scope = TaskScope::new();
    scope.spawn(async move {
        loop {
            x2.changed().await;
            n.set(n.get() + 1);
        }
    });

    batch(|| {
        x.set(1);
        x.set(2);
        x.set(3);
    });
    println!(
        "After 3 sets in a batch: {} notification(s)",
        notifications.get()
    );
    // Should be 1 — not 3.

    println!("\nDone.");
}

examples/scope_bench.rs (line 75)

fn main() {
    println!("=== Auralis Task Scope Benchmarks ===\n");

    // 1. Scope create + destroy (100 tasks)
    let iterations = 50_000;
    init();
    time("scope_100_tasks_create_destroy", iterations, || {
        let scope = TaskScope::new();
        for _ in 0..100 {
            scope.spawn(async {});
        }
        drop(scope);
    });

    // 2. Deep nesting drop (200 levels)
    init();
    time("scope_200_levels_deep_drop", 5_000, || {
        let root = TaskScope::new();
        {
            let mut current = TaskScope::new_child(&root);
            for _ in 0..199 {
                current.spawn(async {});
                current = TaskScope::new_child(&current);
            }
        }
        drop(root);
    });

    // 3. Priority ordering (batched flush)
    {
        let order: Rc<RefCell<Vec<String>>> = Rc::new(RefCell::new(Vec::new()));
        let min_iterations = 5_000;
        // Warm-up
        for _ in 0..500 {
            let sched = BatchedFlush::new();
            init_flush_scheduler(Rc::clone(&sched) as Rc<dyn ScheduleFlush>);
            order.borrow_mut().clear();
            for i in 0..1000 {
                let o = Rc::clone(&order);
                auralis_task::spawn_global_with_priority(Priority::Low, async move {
                    o.borrow_mut().push(format!("low_{i}"));
                });
            }
            for i in 0..10 {
                let o = Rc::clone(&order);
                auralis_task::spawn_global_with_priority(Priority::High, async move {
                    o.borrow_mut().push(format!("high_{i}"));
                });
            }
            sched.drain();
        }

        let start = Instant::now();
        for _ in 0..min_iterations {
            let sched = BatchedFlush::new();
            init_flush_scheduler(Rc::clone(&sched) as Rc<dyn ScheduleFlush>);
            order.borrow_mut().clear();
            for i in 0..1000 {
                let o = Rc::clone(&order);
                auralis_task::spawn_global_with_priority(Priority::Low, async move {
                    o.borrow_mut().push(format!("low_{i}"));
                });
            }
            for i in 0..10 {
                let o = Rc::clone(&order);
                auralis_task::spawn_global_with_priority(Priority::High, async move {
                    o.borrow_mut().push(format!("high_{i}"));
                });
            }
            sched.drain();
            // Verify correctness.
            let result = order.borrow().clone();
            debug_assert_eq!(result.len(), 1010);
        }
        let elapsed = start.elapsed().as_secs_f64() * 1_000_000.0 / min_iterations as f64;
        println!(
            "  {:<42} {:>8.2} µs/iter",
            "priority_1000_low_10_high", elapsed
        );
        init(); // restore sync scheduler
    }

    // 4. Scope churn (100 scopes x 10 tasks, batch drop)
    init();
    time("scope_churn_100x10_batch_drop", 5_000, || {
        let scopes: Vec<TaskScope> = (0..100)
            .map(|_| {
                let s = TaskScope::new();
                for _ in 0..10 {
                    s.spawn(async {});
                }
                s
            })
            .collect();
        drop(scopes);
    });

    // 5. Scope suspend + resume (1000 tasks)
    init();
    let scope = TaskScope::new();
    for _ in 0..1000 {
        scope.spawn(async {});
    }
    time("scope_suspend_resume_1000_tasks", 500_000, || {
        scope.suspend();
        scope.resume();
    });

    // 6. Wide shallow tree drop (50x50, ~2550 tasks)
    init();
    time("scope_wide_tree_50x3_drop", 500, || {
        let root = TaskScope::new();
        for _ in 0..50 {
            let child = TaskScope::new_child(&root);
            child.spawn(async {});
            for _ in 0..50 {
                let grandchild = TaskScope::new_child(&child);
                grandchild.spawn(async {});
            }
        }
        drop(root);
    });

    println!("\n=== Done ===");
}

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.

Examples found in repository

examples/multi_instance_isolated.rs (line 32)

fn handle_request(request_id: u32) -> String {
    let ex = Executor::new_instance();
    Executor::install_flush_scheduler(&ex, Rc::new(SyncScheduler));

    let scope = TaskScope::with_executor(&ex);
    let data = Signal::new(String::new());

    // "route handler" spawns a reactive effect
    let d = data.clone();
    scope.spawn(async move {
        loop {
            d.changed().await;
            let val = d.read();
            if val == "done" {
                break;
            }
        }
    });

    // "middleware" sets up cleanup
    let cleanup_called = Rc::new(Cell::new(false));
    let cc = Rc::clone(&cleanup_called);
    scope.on_cleanup(move || cc.set(true));

    // "business logic" — would be I/O in real app
    let result = auralis_task::with_executor(&ex, || {
        data.set(format!("request {request_id}: processing"));
        data.set(format!("request {request_id}: done"));
        data.read()
    });

    // Drop scope → cancels effect, runs cleanup.
    drop(scope);

    assert!(cleanup_called.get());
    result
}

fn main() {
    // ---- Pattern 1: sequential requests (same thread, isolated) ----------
    println!("=== 1. Sequential request isolation ===");
    let r1 = handle_request(1);
    let r2 = handle_request(2);
    println!("  {r1}");
    println!("  {r2}");
    assert_eq!(r1, "request 1: done");
    assert_eq!(r2, "request 2: done");

    // ---- Pattern 2: same-signal isolation test (different executors) -----
    println!("\n=== 2. Cross-executor signal isolation ===");
    {
        let ex_a = Executor::new_instance();
        Executor::install_flush_scheduler(&ex_a, Rc::new(SyncScheduler));
        let ex_b = Executor::new_instance();
        Executor::install_flush_scheduler(&ex_b, Rc::new(SyncScheduler));

        let sig_a1 = Signal::new(0i32);
        let sig_b1 = Signal::new(0i32);

        // Scope on executor A sets sig_a and reads sig_b.
        let scope_a = TaskScope::with_executor(&ex_a);
        let a_val = Rc::new(RefCell::new(Vec::new()));
        let av = Rc::clone(&a_val);
        {
            let s = sig_a1.clone();
            scope_a.spawn(async move {
                s.set(42);
                av.borrow_mut().push(s.read());
            });
        }
        drop(scope_a);

        // Scope on executor B sets sig_b and reads sig_a.
        let scope_b = TaskScope::with_executor(&ex_b);
        let b_val = Rc::new(RefCell::new(Vec::new()));
        let bv = Rc::clone(&b_val);
        {
            let s = sig_b1.clone();
            scope_b.spawn(async move {
                s.set(99);
                bv.borrow_mut().push(s.read());
            });
        }
        drop(scope_b);

        // Each executor only sees its own signal changes.
        assert_eq!(*a_val.borrow(), vec![42]);
        assert_eq!(*b_val.borrow(), vec![99]);
        assert_eq!(sig_a1.read(), 42);
        assert_eq!(sig_b1.read(), 99);
    }

    // ---- Pattern 3: the SSR mental model (one request = one executor) ----
    println!("\n=== 3. SSR mental model ===");
    for i in 0..3 {
        let ex = Executor::new_instance();
        Executor::install_flush_scheduler(&ex, Rc::new(SyncScheduler));
        let counter = Signal::new(0i32);

        let scope = TaskScope::with_executor(&ex);
        let c = counter.clone();
        let results = Rc::new(RefCell::new(Vec::new()));
        let res = Rc::clone(&results);

        scope.spawn(async move {
            loop {
                c.changed().await;
                let v = c.read();
                res.borrow_mut().push(v);
                if v >= 3 {
                    break;
                }
            }
        });

        auralis_task::with_executor(&ex, || {
            counter.set(1);
            counter.set(2);
            counter.set(3);
        });

        drop(scope);
        assert_eq!(*results.borrow(), vec![1, 2, 3]);
        println!("  request {i}: signals {:?}", results.borrow());
    }

    println!("\nAll patterns completed — zero cross-request leakage.");
}

pub fn new_child(parent: &Self) -> Self

Create a child scope that inherits the parent’s executor.

The child is stored in the parent’s children list. This means dropping all external clones of the child does not immediately cancel it — the parent’s strong reference keeps it alive. The child is fully cancelled only when the parent itself is dropped (or when TaskScope::drop runs on the last reference).

To explicitly cancel a child while the parent is still alive, call suspend on the child, or use a JoinHandle to cancel individual tasks.

Examples found in repository

examples/scope_bench.rs (line 87)

fn main() {
    println!("=== Auralis Task Scope Benchmarks ===\n");

    // 1. Scope create + destroy (100 tasks)
    let iterations = 50_000;
    init();
    time("scope_100_tasks_create_destroy", iterations, || {
        let scope = TaskScope::new();
        for _ in 0..100 {
            scope.spawn(async {});
        }
        drop(scope);
    });

    // 2. Deep nesting drop (200 levels)
    init();
    time("scope_200_levels_deep_drop", 5_000, || {
        let root = TaskScope::new();
        {
            let mut current = TaskScope::new_child(&root);
            for _ in 0..199 {
                current.spawn(async {});
                current = TaskScope::new_child(&current);
            }
        }
        drop(root);
    });

    // 3. Priority ordering (batched flush)
    {
        let order: Rc<RefCell<Vec<String>>> = Rc::new(RefCell::new(Vec::new()));
        let min_iterations = 5_000;
        // Warm-up
        for _ in 0..500 {
            let sched = BatchedFlush::new();
            init_flush_scheduler(Rc::clone(&sched) as Rc<dyn ScheduleFlush>);
            order.borrow_mut().clear();
            for i in 0..1000 {
                let o = Rc::clone(&order);
                auralis_task::spawn_global_with_priority(Priority::Low, async move {
                    o.borrow_mut().push(format!("low_{i}"));
                });
            }
            for i in 0..10 {
                let o = Rc::clone(&order);
                auralis_task::spawn_global_with_priority(Priority::High, async move {
                    o.borrow_mut().push(format!("high_{i}"));
                });
            }
            sched.drain();
        }

        let start = Instant::now();
        for _ in 0..min_iterations {
            let sched = BatchedFlush::new();
            init_flush_scheduler(Rc::clone(&sched) as Rc<dyn ScheduleFlush>);
            order.borrow_mut().clear();
            for i in 0..1000 {
                let o = Rc::clone(&order);
                auralis_task::spawn_global_with_priority(Priority::Low, async move {
                    o.borrow_mut().push(format!("low_{i}"));
                });
            }
            for i in 0..10 {
                let o = Rc::clone(&order);
                auralis_task::spawn_global_with_priority(Priority::High, async move {
                    o.borrow_mut().push(format!("high_{i}"));
                });
            }
            sched.drain();
            // Verify correctness.
            let result = order.borrow().clone();
            debug_assert_eq!(result.len(), 1010);
        }
        let elapsed = start.elapsed().as_secs_f64() * 1_000_000.0 / min_iterations as f64;
        println!(
            "  {:<42} {:>8.2} µs/iter",
            "priority_1000_low_10_high", elapsed
        );
        init(); // restore sync scheduler
    }

    // 4. Scope churn (100 scopes x 10 tasks, batch drop)
    init();
    time("scope_churn_100x10_batch_drop", 5_000, || {
        let scopes: Vec<TaskScope> = (0..100)
            .map(|_| {
                let s = TaskScope::new();
                for _ in 0..10 {
                    s.spawn(async {});
                }
                s
            })
            .collect();
        drop(scopes);
    });

    // 5. Scope suspend + resume (1000 tasks)
    init();
    let scope = TaskScope::new();
    for _ in 0..1000 {
        scope.spawn(async {});
    }
    time("scope_suspend_resume_1000_tasks", 500_000, || {
        scope.suspend();
        scope.resume();
    });

    // 6. Wide shallow tree drop (50x50, ~2550 tasks)
    init();
    time("scope_wide_tree_50x3_drop", 500, || {
        let root = TaskScope::new();
        for _ in 0..50 {
            let child = TaskScope::new_child(&root);
            child.spawn(async {});
            for _ in 0..50 {
                let grandchild = TaskScope::new_child(&child);
                grandchild.spawn(async {});
            }
        }
        drop(root);
    });

    println!("\n=== Done ===");
}

pub fn spawn(&self, future: impl Future<Output = ()> + 'static) -> JoinHandle

Spawn a future in this scope at low priority.

Returns a JoinHandle that can cancel this individual task. Drop the handle to detach (the task keeps running until the scope is dropped).

Examples found in repository

examples/multi_instance_isolated.rs (lines 37-45)

fn handle_request(request_id: u32) -> String {
    let ex = Executor::new_instance();
    Executor::install_flush_scheduler(&ex, Rc::new(SyncScheduler));

    let scope = TaskScope::with_executor(&ex);
    let data = Signal::new(String::new());

    // "route handler" spawns a reactive effect
    let d = data.clone();
    scope.spawn(async move {
        loop {
            d.changed().await;
            let val = d.read();
            if val == "done" {
                break;
            }
        }
    });

    // "middleware" sets up cleanup
    let cleanup_called = Rc::new(Cell::new(false));
    let cc = Rc::clone(&cleanup_called);
    scope.on_cleanup(move || cc.set(true));

    // "business logic" — would be I/O in real app
    let result = auralis_task::with_executor(&ex, || {
        data.set(format!("request {request_id}: processing"));
        data.set(format!("request {request_id}: done"));
        data.read()
    });

    // Drop scope → cancels effect, runs cleanup.
    drop(scope);

    assert!(cleanup_called.get());
    result
}

fn main() {
    // ---- Pattern 1: sequential requests (same thread, isolated) ----------
    println!("=== 1. Sequential request isolation ===");
    let r1 = handle_request(1);
    let r2 = handle_request(2);
    println!("  {r1}");
    println!("  {r2}");
    assert_eq!(r1, "request 1: done");
    assert_eq!(r2, "request 2: done");

    // ---- Pattern 2: same-signal isolation test (different executors) -----
    println!("\n=== 2. Cross-executor signal isolation ===");
    {
        let ex_a = Executor::new_instance();
        Executor::install_flush_scheduler(&ex_a, Rc::new(SyncScheduler));
        let ex_b = Executor::new_instance();
        Executor::install_flush_scheduler(&ex_b, Rc::new(SyncScheduler));

        let sig_a1 = Signal::new(0i32);
        let sig_b1 = Signal::new(0i32);

        // Scope on executor A sets sig_a and reads sig_b.
        let scope_a = TaskScope::with_executor(&ex_a);
        let a_val = Rc::new(RefCell::new(Vec::new()));
        let av = Rc::clone(&a_val);
        {
            let s = sig_a1.clone();
            scope_a.spawn(async move {
                s.set(42);
                av.borrow_mut().push(s.read());
            });
        }
        drop(scope_a);

        // Scope on executor B sets sig_b and reads sig_a.
        let scope_b = TaskScope::with_executor(&ex_b);
        let b_val = Rc::new(RefCell::new(Vec::new()));
        let bv = Rc::clone(&b_val);
        {
            let s = sig_b1.clone();
            scope_b.spawn(async move {
                s.set(99);
                bv.borrow_mut().push(s.read());
            });
        }
        drop(scope_b);

        // Each executor only sees its own signal changes.
        assert_eq!(*a_val.borrow(), vec![42]);
        assert_eq!(*b_val.borrow(), vec![99]);
        assert_eq!(sig_a1.read(), 42);
        assert_eq!(sig_b1.read(), 99);
    }

    // ---- Pattern 3: the SSR mental model (one request = one executor) ----
    println!("\n=== 3. SSR mental model ===");
    for i in 0..3 {
        let ex = Executor::new_instance();
        Executor::install_flush_scheduler(&ex, Rc::new(SyncScheduler));
        let counter = Signal::new(0i32);

        let scope = TaskScope::with_executor(&ex);
        let c = counter.clone();
        let results = Rc::new(RefCell::new(Vec::new()));
        let res = Rc::clone(&results);

        scope.spawn(async move {
            loop {
                c.changed().await;
                let v = c.read();
                res.borrow_mut().push(v);
                if v >= 3 {
                    break;
                }
            }
        });

        auralis_task::with_executor(&ex, || {
            counter.set(1);
            counter.set(2);
            counter.set(3);
        });

        drop(scope);
        assert_eq!(*results.borrow(), vec![1, 2, 3]);
        println!("  request {i}: signals {:?}", results.borrow());
    }

    println!("\nAll patterns completed — zero cross-request leakage.");
}

examples/counter.rs (lines 67-72)

fn main() {
    // One-time executor setup.
    init_flush_scheduler(Rc::new(CliScheduler));
    init_time_source(Rc::new(CliClock::new()));

    // ---- Signal basics ----
    println!("=== Signal basics ===");
    let count = Signal::new(0);
    println!("count = {}", count.read());
    count.set(42);
    println!("count = {}", count.read());

    // ---- Memo (auto-tracking computed value) ----
    println!("\n=== Memo ===");
    let a = Signal::new(2);
    let b = Signal::new(3);
    let a2 = a.clone();
    let b2 = b.clone();
    let sum = Memo::new(move || a2.read() + b2.read());
    println!("2 + 3 = {}", sum.read());
    a.set(10);
    println!("10 + 3 = {}", sum.read());

    // ---- TaskScope: spawn a task that watches a signal ----
    println!("\n=== TaskScope (scoped signal watcher) ===");
    let messages = Signal::new(vec!["hello".to_string()]);

    {
        let scope = TaskScope::new();
        let msgs = messages.clone();
        scope.spawn(async move {
            loop {
                let val = msgs.changed().await;
                println!("  task observed: {:?}", val);
            }
        });

        messages.set(vec!["hello".to_string(), "world".to_string()]);
        messages.set(vec![
            "hello".to_string(),
            "world".to_string(),
            "!".to_string(),
        ]);

        // Explicit drop — cancels the task and cleans up resources.
        drop(scope);
    }
    println!("(scope dropped — task and subscriptions cleaned up)");

    // ---- Batch: multiple sets, one notification ----
    println!("\n=== Batch ===");
    let x = Signal::new(0);
    let notifications = Rc::new(Cell::new(0u32));
    let n = Rc::clone(&notifications);
    let x2 = x.clone();

    let scope = TaskScope::new();
    scope.spawn(async move {
        loop {
            x2.changed().await;
            n.set(n.get() + 1);
        }
    });

    batch(|| {
        x.set(1);
        x.set(2);
        x.set(3);
    });
    println!(
        "After 3 sets in a batch: {} notification(s)",
        notifications.get()
    );
    // Should be 1 — not 3.

    println!("\nDone.");
}

examples/scope_bench.rs (line 77)

fn main() {
    println!("=== Auralis Task Scope Benchmarks ===\n");

    // 1. Scope create + destroy (100 tasks)
    let iterations = 50_000;
    init();
    time("scope_100_tasks_create_destroy", iterations, || {
        let scope = TaskScope::new();
        for _ in 0..100 {
            scope.spawn(async {});
        }
        drop(scope);
    });

    // 2. Deep nesting drop (200 levels)
    init();
    time("scope_200_levels_deep_drop", 5_000, || {
        let root = TaskScope::new();
        {
            let mut current = TaskScope::new_child(&root);
            for _ in 0..199 {
                current.spawn(async {});
                current = TaskScope::new_child(&current);
            }
        }
        drop(root);
    });

    // 3. Priority ordering (batched flush)
    {
        let order: Rc<RefCell<Vec<String>>> = Rc::new(RefCell::new(Vec::new()));
        let min_iterations = 5_000;
        // Warm-up
        for _ in 0..500 {
            let sched = BatchedFlush::new();
            init_flush_scheduler(Rc::clone(&sched) as Rc<dyn ScheduleFlush>);
            order.borrow_mut().clear();
            for i in 0..1000 {
                let o = Rc::clone(&order);
                auralis_task::spawn_global_with_priority(Priority::Low, async move {
                    o.borrow_mut().push(format!("low_{i}"));
                });
            }
            for i in 0..10 {
                let o = Rc::clone(&order);
                auralis_task::spawn_global_with_priority(Priority::High, async move {
                    o.borrow_mut().push(format!("high_{i}"));
                });
            }
            sched.drain();
        }

        let start = Instant::now();
        for _ in 0..min_iterations {
            let sched = BatchedFlush::new();
            init_flush_scheduler(Rc::clone(&sched) as Rc<dyn ScheduleFlush>);
            order.borrow_mut().clear();
            for i in 0..1000 {
                let o = Rc::clone(&order);
                auralis_task::spawn_global_with_priority(Priority::Low, async move {
                    o.borrow_mut().push(format!("low_{i}"));
                });
            }
            for i in 0..10 {
                let o = Rc::clone(&order);
                auralis_task::spawn_global_with_priority(Priority::High, async move {
                    o.borrow_mut().push(format!("high_{i}"));
                });
            }
            sched.drain();
            // Verify correctness.
            let result = order.borrow().clone();
            debug_assert_eq!(result.len(), 1010);
        }
        let elapsed = start.elapsed().as_secs_f64() * 1_000_000.0 / min_iterations as f64;
        println!(
            "  {:<42} {:>8.2} µs/iter",
            "priority_1000_low_10_high", elapsed
        );
        init(); // restore sync scheduler
    }

    // 4. Scope churn (100 scopes x 10 tasks, batch drop)
    init();
    time("scope_churn_100x10_batch_drop", 5_000, || {
        let scopes: Vec<TaskScope> = (0..100)
            .map(|_| {
                let s = TaskScope::new();
                for _ in 0..10 {
                    s.spawn(async {});
                }
                s
            })
            .collect();
        drop(scopes);
    });

    // 5. Scope suspend + resume (1000 tasks)
    init();
    let scope = TaskScope::new();
    for _ in 0..1000 {
        scope.spawn(async {});
    }
    time("scope_suspend_resume_1000_tasks", 500_000, || {
        scope.suspend();
        scope.resume();
    });

    // 6. Wide shallow tree drop (50x50, ~2550 tasks)
    init();
    time("scope_wide_tree_50x3_drop", 500, || {
        let root = TaskScope::new();
        for _ in 0..50 {
            let child = TaskScope::new_child(&root);
            child.spawn(async {});
            for _ in 0..50 {
                let grandchild = TaskScope::new_child(&child);
                grandchild.spawn(async {});
            }
        }
        drop(root);
    });

    println!("\n=== Done ===");
}

pub fn spawn_with_priority( &self, priority: Priority, future: impl Future<Output = ()> + 'static, ) -> JoinHandle

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.

Returns a JoinHandle that can cancel this individual task.

pub fn watch<T: Clone + 'static>( &self, sig: &Signal<T>, f: impl FnMut(&T) + 'static, ) -> JoinHandle

Spawn a task that calls f with the new value whenever sig changes.

This is a convenience wrapper around the common pattern:

scope.spawn({
    let s = sig.clone();
    async move { loop { s.changed().await; f(&s.read()); } }
});

Returns a JoinHandle for individual cancellation.

pub fn watch_effect(&self, effect: impl Fn() + 'static) -> JoinHandle

Spawn a task that re-runs effect whenever any Signal read inside it changes — using a Memo internally to auto-track dependencies.

The effect is run once immediately to discover its dependencies. Subsequent runs happen on the executor when a dependency changes.

Returns a JoinHandle for individual cancellation.

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.

pub fn on_cleanup(&self, f: impl FnOnce() + 'static)

Register a cleanup function that runs when this scope is dropped.

Equivalent to register_callback_handle(CallbackHandle::new(f)).

Cleanup functions run before spawned tasks are cancelled, so they can safely interact with signals and other resources.

If the scope is already cancelled, f is dropped immediately.

Examples found in repository

examples/multi_instance_isolated.rs (line 50)

fn handle_request(request_id: u32) -> String {
    let ex = Executor::new_instance();
    Executor::install_flush_scheduler(&ex, Rc::new(SyncScheduler));

    let scope = TaskScope::with_executor(&ex);
    let data = Signal::new(String::new());

    // "route handler" spawns a reactive effect
    let d = data.clone();
    scope.spawn(async move {
        loop {
            d.changed().await;
            let val = d.read();
            if val == "done" {
                break;
            }
        }
    });

    // "middleware" sets up cleanup
    let cleanup_called = Rc::new(Cell::new(false));
    let cc = Rc::clone(&cleanup_called);
    scope.on_cleanup(move || cc.set(true));

    // "business logic" — would be I/O in real app
    let result = auralis_task::with_executor(&ex, || {
        data.set(format!("request {request_id}: processing"));
        data.set(format!("request {request_id}: done"));
        data.read()
    });

    // Drop scope → cancels effect, runs cleanup.
    drop(scope);

    assert!(cleanup_called.get());
    result
}

pub fn provide<T: 'static>(&self, value: T)

Store a value of type T in this scope.

The value is wrapped in Rc so it can be shared. A subsequent call to consume on this scope (or any descendant) will discover it by walking up the parent chain.

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.

pub fn expect_context<T: 'static>(&self) -> Rc<T>

Like consume but panics if the value is not found.

Panics

Panics if no ancestor scope has provided a value of type T.

pub fn is_cancelled(&self) -> bool

Return true if this scope has been cancelled (dropped).

A cancelled scope silently ignores spawn calls.

pub fn set_label(&self, label: impl Into<String>)

Set a human-readable label for this scope.

Labels appear in dump_reactive_graph() output and are useful for debugging.

pub fn label(&self) -> Option<String>

Return the label set by set_label, if any.

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.

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.

Examples found in repository

examples/scope_bench.rs (line 172)

fn main() {
    println!("=== Auralis Task Scope Benchmarks ===\n");

    // 1. Scope create + destroy (100 tasks)
    let iterations = 50_000;
    init();
    time("scope_100_tasks_create_destroy", iterations, || {
        let scope = TaskScope::new();
        for _ in 0..100 {
            scope.spawn(async {});
        }
        drop(scope);
    });

    // 2. Deep nesting drop (200 levels)
    init();
    time("scope_200_levels_deep_drop", 5_000, || {
        let root = TaskScope::new();
        {
            let mut current = TaskScope::new_child(&root);
            for _ in 0..199 {
                current.spawn(async {});
                current = TaskScope::new_child(&current);
            }
        }
        drop(root);
    });

    // 3. Priority ordering (batched flush)
    {
        let order: Rc<RefCell<Vec<String>>> = Rc::new(RefCell::new(Vec::new()));
        let min_iterations = 5_000;
        // Warm-up
        for _ in 0..500 {
            let sched = BatchedFlush::new();
            init_flush_scheduler(Rc::clone(&sched) as Rc<dyn ScheduleFlush>);
            order.borrow_mut().clear();
            for i in 0..1000 {
                let o = Rc::clone(&order);
                auralis_task::spawn_global_with_priority(Priority::Low, async move {
                    o.borrow_mut().push(format!("low_{i}"));
                });
            }
            for i in 0..10 {
                let o = Rc::clone(&order);
                auralis_task::spawn_global_with_priority(Priority::High, async move {
                    o.borrow_mut().push(format!("high_{i}"));
                });
            }
            sched.drain();
        }

        let start = Instant::now();
        for _ in 0..min_iterations {
            let sched = BatchedFlush::new();
            init_flush_scheduler(Rc::clone(&sched) as Rc<dyn ScheduleFlush>);
            order.borrow_mut().clear();
            for i in 0..1000 {
                let o = Rc::clone(&order);
                auralis_task::spawn_global_with_priority(Priority::Low, async move {
                    o.borrow_mut().push(format!("low_{i}"));
                });
            }
            for i in 0..10 {
                let o = Rc::clone(&order);
                auralis_task::spawn_global_with_priority(Priority::High, async move {
                    o.borrow_mut().push(format!("high_{i}"));
                });
            }
            sched.drain();
            // Verify correctness.
            let result = order.borrow().clone();
            debug_assert_eq!(result.len(), 1010);
        }
        let elapsed = start.elapsed().as_secs_f64() * 1_000_000.0 / min_iterations as f64;
        println!(
            "  {:<42} {:>8.2} µs/iter",
            "priority_1000_low_10_high", elapsed
        );
        init(); // restore sync scheduler
    }

    // 4. Scope churn (100 scopes x 10 tasks, batch drop)
    init();
    time("scope_churn_100x10_batch_drop", 5_000, || {
        let scopes: Vec<TaskScope> = (0..100)
            .map(|_| {
                let s = TaskScope::new();
                for _ in 0..10 {
                    s.spawn(async {});
                }
                s
            })
            .collect();
        drop(scopes);
    });

    // 5. Scope suspend + resume (1000 tasks)
    init();
    let scope = TaskScope::new();
    for _ in 0..1000 {
        scope.spawn(async {});
    }
    time("scope_suspend_resume_1000_tasks", 500_000, || {
        scope.suspend();
        scope.resume();
    });

    // 6. Wide shallow tree drop (50x50, ~2550 tasks)
    init();
    time("scope_wide_tree_50x3_drop", 500, || {
        let root = TaskScope::new();
        for _ in 0..50 {
            let child = TaskScope::new_child(&root);
            child.spawn(async {});
            for _ in 0..50 {
                let grandchild = TaskScope::new_child(&child);
                grandchild.spawn(async {});
            }
        }
        drop(root);
    });

    println!("\n=== Done ===");
}

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.

Examples found in repository

examples/scope_bench.rs (line 173)

fn main() {
    println!("=== Auralis Task Scope Benchmarks ===\n");

    // 1. Scope create + destroy (100 tasks)
    let iterations = 50_000;
    init();
    time("scope_100_tasks_create_destroy", iterations, || {
        let scope = TaskScope::new();
        for _ in 0..100 {
            scope.spawn(async {});
        }
        drop(scope);
    });

    // 2. Deep nesting drop (200 levels)
    init();
    time("scope_200_levels_deep_drop", 5_000, || {
        let root = TaskScope::new();
        {
            let mut current = TaskScope::new_child(&root);
            for _ in 0..199 {
                current.spawn(async {});
                current = TaskScope::new_child(&current);
            }
        }
        drop(root);
    });

    // 3. Priority ordering (batched flush)
    {
        let order: Rc<RefCell<Vec<String>>> = Rc::new(RefCell::new(Vec::new()));
        let min_iterations = 5_000;
        // Warm-up
        for _ in 0..500 {
            let sched = BatchedFlush::new();
            init_flush_scheduler(Rc::clone(&sched) as Rc<dyn ScheduleFlush>);
            order.borrow_mut().clear();
            for i in 0..1000 {
                let o = Rc::clone(&order);
                auralis_task::spawn_global_with_priority(Priority::Low, async move {
                    o.borrow_mut().push(format!("low_{i}"));
                });
            }
            for i in 0..10 {
                let o = Rc::clone(&order);
                auralis_task::spawn_global_with_priority(Priority::High, async move {
                    o.borrow_mut().push(format!("high_{i}"));
                });
            }
            sched.drain();
        }

        let start = Instant::now();
        for _ in 0..min_iterations {
            let sched = BatchedFlush::new();
            init_flush_scheduler(Rc::clone(&sched) as Rc<dyn ScheduleFlush>);
            order.borrow_mut().clear();
            for i in 0..1000 {
                let o = Rc::clone(&order);
                auralis_task::spawn_global_with_priority(Priority::Low, async move {
                    o.borrow_mut().push(format!("low_{i}"));
                });
            }
            for i in 0..10 {
                let o = Rc::clone(&order);
                auralis_task::spawn_global_with_priority(Priority::High, async move {
                    o.borrow_mut().push(format!("high_{i}"));
                });
            }
            sched.drain();
            // Verify correctness.
            let result = order.borrow().clone();
            debug_assert_eq!(result.len(), 1010);
        }
        let elapsed = start.elapsed().as_secs_f64() * 1_000_000.0 / min_iterations as f64;
        println!(
            "  {:<42} {:>8.2} µs/iter",
            "priority_1000_low_10_high", elapsed
        );
        init(); // restore sync scheduler
    }

    // 4. Scope churn (100 scopes x 10 tasks, batch drop)
    init();
    time("scope_churn_100x10_batch_drop", 5_000, || {
        let scopes: Vec<TaskScope> = (0..100)
            .map(|_| {
                let s = TaskScope::new();
                for _ in 0..10 {
                    s.spawn(async {});
                }
                s
            })
            .collect();
        drop(scopes);
    });

    // 5. Scope suspend + resume (1000 tasks)
    init();
    let scope = TaskScope::new();
    for _ in 0..1000 {
        scope.spawn(async {});
    }
    time("scope_suspend_resume_1000_tasks", 500_000, || {
        scope.suspend();
        scope.resume();
    });

    // 6. Wide shallow tree drop (50x50, ~2550 tasks)
    init();
    time("scope_wide_tree_50x3_drop", 500, || {
        let root = TaskScope::new();
        for _ in 0..50 {
            let child = TaskScope::new_child(&root);
            child.spawn(async {});
            for _ in 0..50 {
                let grandchild = TaskScope::new_child(&child);
                grandchild.spawn(async {});
            }
        }
        drop(root);
    });

    println!("\n=== Done ===");
}

pub fn is_suspended(&self) -> bool

Return true if this scope is currently suspended.

Trait Implementations

impl Clone for TaskScope

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Default for TaskScope

fn default() -> Self

Returns the “default value” for a type.

impl Drop for TaskScope

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.