Struct ThreadedDispatcher 

pub struct ThreadedDispatcher { /* private fields */ }

A [PlatformDispatcher] that runs background work on real threads, for tests and benchmarks.

Background tasks run in parallel on a pool of worker threads, and timers fire in real time on a timer thread. Main-thread tasks wait in a queue until the creating thread runs them with Self::run_until_idle, because no platform run loop does that here.

Use this when a test needs production concurrency. For deterministic scheduling on one thread with a virtual clock, use TestDispatcher instead.

Examples

use std::sync::{
    Arc,
    atomic::{AtomicUsize, Ordering},
};

use gpui::{BackgroundExecutor, ForegroundExecutor, ThreadedDispatcher};

let dispatcher = Arc::new(ThreadedDispatcher::new());
let background = BackgroundExecutor::new(dispatcher.clone());
let foreground = ForegroundExecutor::new(dispatcher.clone());
let total = Arc::new(AtomicUsize::new(0));

let background_total = total.clone();
background
    .spawn(async move {
        background_total.fetch_add(1, Ordering::SeqCst);
    })
    .detach();

let main_total = total.clone();
foreground
    .spawn(async move {
        main_total.fetch_add(10, Ordering::SeqCst);
    })
    .detach();

// Runs the main-thread task, and waits for the background task to finish.
dispatcher.run_until_idle();
assert_eq!(total.load(Ordering::SeqCst), 11);

Implementations

impl ThreadedDispatcher

pub fn new() -> Self

Creates a dispatcher whose main thread is the calling thread.

It starts one worker thread per available CPU, with at least two, and one timer thread. The worker threads stop when the dispatcher is dropped, but the timer thread runs for the rest of the process, so create one dispatcher and reuse it.

pub fn run_until_idle(&self)

Runs queued main thread tasks and waits until no background or timer work is queued, running, or already due.

Timers that haven’t reached their due time yet are not waited for: the dispatcher runs in real time and cannot skip ahead like the TestDispatcher’s virtual clock, so waiting on a future timer would block for its full real duration. Tasks sleeping on such timers are considered idle. Must be called on the thread that created this dispatcher.

pub fn run_ready_main_tasks(&self) -> bool

Runs up to the initial queue length of main-thread tasks.

Returns whether any ran. This snapshots the count, not task identities: newly dispatched higher-priority tasks can overtake the original tasks.

pub fn cancel_pending_timers(&self) -> usize

Cancels every armed timer, and returns how many were canceled.

Use it between workloads that share one dispatcher, so a timer from the earlier workload can’t fire during the later one. Dropping a timer drops its completion sender, which wakes the task that was awaiting it. Call Self::run_until_idle afterwards to run the work that the cancellation unblocks.

pub fn debug_state(&self) -> String

Returns a one-line summary of the dispatcher’s idle-tracking state.

The summary lists the number of in-flight background and timer runnables, the number of armed timers, and whether main-thread work is queued. Use it to find out why Self::run_until_idle doesn’t return.

Trait Implementations

impl Default for ThreadedDispatcher

fn default() -> Self

Returns the “default value” for a type.