Skip to main content

guic_gpui_scheduler/
scheduler.rs

1mod clock;
2mod executor;
3mod test_scheduler;
4#[cfg(test)]
5mod tests;
6
7pub use clock::*;
8pub use executor::*;
9pub use test_scheduler::*;
10
11use async_task::Runnable;
12use futures::channel::oneshot;
13use std::{
14    any::Any,
15    future::Future,
16    panic::Location,
17    pin::Pin,
18    sync::Arc,
19    task::{Context, Poll},
20    thread,
21    time::Duration,
22};
23
24/// Type-erased work scheduled on a dedicated local executor.
25pub type DedicatedTask = Box<
26    dyn FnOnce(LocalExecutor) -> Pin<Box<dyn Future<Output = Box<dyn Any + Send + Sync>> + 'static>>
27        + Send
28        + 'static,
29>;
30
31/// Task priority for background tasks.
32///
33/// Higher priority tasks are more likely to be scheduled before lower priority tasks,
34/// but this is not a strict guarantee - the scheduler may interleave tasks of different
35/// priorities to prevent starvation.
36#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
37#[repr(u8)]
38pub enum Priority {
39    /// Realtime priority
40    ///
41    /// Spawning a task with this priority will spin it off on a separate thread dedicated just to that task. Only use for audio.
42    RealtimeAudio,
43    /// High priority - use for tasks critical to user experience/responsiveness.
44    High,
45    /// Medium priority - suitable for most use cases.
46    #[default]
47    Medium,
48    /// Low priority - use for background work that can be deprioritized.
49    Low,
50}
51
52impl Priority {
53    /// Returns the relative probability weight for this priority level.
54    /// Used by schedulers to determine task selection probability.
55    pub const fn weight(self) -> u32 {
56        match self {
57            Priority::High => 60,
58            Priority::Medium => 30,
59            Priority::Low => 10,
60            // realtime priorities are not considered for probability scheduling
61            Priority::RealtimeAudio => 0,
62        }
63    }
64}
65
66#[derive(Clone, Copy, Debug)]
67pub struct SpawnTime(pub Instant);
68
69/// Metadata attached to runnables for debugging and profiling.
70#[derive(Clone, Debug)]
71pub struct RunnableMeta {
72    /// The source location where the task was spawned.
73    pub location: &'static Location<'static>,
74    /// The moment the task was spawned.
75    pub spawned: SpawnTime,
76}
77
78impl RunnableMeta {
79    #[track_caller]
80    pub fn new_with_callers_location() -> Self {
81        Self {
82            location: core::panic::Location::caller(),
83            spawned: SpawnTime(Instant::now()),
84        }
85    }
86}
87
88pub trait Scheduler: Send + Sync {
89    /// Block until the given future completes or timeout occurs.
90    ///
91    /// Returns `true` if the future completed, `false` if it timed out.
92    /// The future is passed as a pinned mutable reference so the caller
93    /// retains ownership and can continue polling or return it on timeout.
94    fn block(
95        &self,
96        session_id: Option<SessionId>,
97        future: Pin<&mut dyn Future<Output = ()>>,
98        timeout: Option<Duration>,
99    ) -> bool;
100
101    /// Schedule a runnable on the local (session-pinned) queue for `session_id`.
102    /// Runnables scheduled here run in order on whichever thread drains the
103    /// session — the main thread for ordinary sessions, or a dedicated OS
104    /// thread for sessions created via `spawn_dedicated_thread`.
105    fn schedule_local(&self, session_id: SessionId, runnable: Runnable<RunnableMeta>);
106
107    /// Schedule a background task with the given priority.
108    fn schedule_background_with_priority(
109        &self,
110        runnable: Runnable<RunnableMeta>,
111        priority: Priority,
112    );
113
114    /// Spawn a closure on a dedicated realtime thread for audio processing.
115    fn spawn_realtime(&self, f: Box<dyn FnOnce() + Send>);
116
117    /// Schedule a background task with default (medium) priority.
118    fn schedule_background(&self, runnable: Runnable<RunnableMeta>) {
119        self.schedule_background_with_priority(runnable, Priority::default());
120    }
121
122    #[track_caller]
123    fn timer(&self, timeout: Duration) -> Timer;
124    fn clock(&self) -> Arc<dyn Clock>;
125
126    /// Spawn a closure on a fresh session pinned to its own [`LocalExecutor`].
127    ///
128    /// `PlatformScheduler` runs the closure on a new OS thread (see
129    /// [`spawn_dedicated_thread`]). `TestScheduler` runs it on the test
130    /// scheduler's loop alongside everything else so determinism under
131    /// `TestScheduler::many` is preserved.
132    ///
133    /// This is the dyn-safe entry point: the closure's output is type-erased
134    /// as `Box<dyn Any + Send + Sync>` so the trait stays object-safe.
135    /// Callers typically reach for the type-safe wrappers on
136    /// [`LocalExecutor::spawn_dedicated`] and
137    /// [`BackgroundExecutor::spawn_dedicated`], which compose this method
138    /// with [`Task::downcast`] to recover the closure's concrete return type.
139    fn spawn_dedicated(self: Arc<Self>, f: DedicatedTask) -> Task<Box<dyn Any + Send + Sync>>;
140
141    fn as_test(&self) -> Option<&TestScheduler> {
142        None
143    }
144}
145
146/// Spawn work on a fresh OS thread that's exclusive to the returned task and
147/// anything spawned on the executor it provides. Blocking syscalls inside that
148/// work don't disturb any other executor in the process.
149///
150/// `f` is called on the dedicated thread with a [`LocalExecutor`] pinned
151/// to it. The future `f` returns may freely be `!Send`. The returned `Task` is
152/// that future's task: dropping it cancels the root, but detached children
153/// keep running until they finish. The thread shuts down once the executor and
154/// every task on it are gone.
155///
156/// The caller is responsible for supplying a `session_id` that's distinct from
157/// every other live session on `scheduler`. Concrete schedulers typically wrap
158/// this in an inherent method that allocates the id from their own counter.
159pub fn spawn_dedicated_thread<F, Fut>(
160    session_id: SessionId,
161    scheduler: Arc<dyn Scheduler>,
162    f: F,
163) -> Task<Fut::Output>
164where
165    F: FnOnce(LocalExecutor) -> Fut + Send + 'static,
166    Fut: Future + 'static,
167    Fut::Output: Send + 'static,
168{
169    let (runnable_sender, runnable_receiver) = flume::unbounded::<Runnable<RunnableMeta>>();
170    let (task_sender, task_receiver) = flume::bounded::<Task<Fut::Output>>(1);
171
172    thread::Builder::new()
173        .name(format!("spawn_dedicated session {:?}", session_id))
174        .spawn(move || {
175            let dispatch = move |runnable: Runnable<RunnableMeta>| {
176                let _ = runnable_sender.send(runnable);
177            };
178            let executor = LocalExecutor::new(session_id, scheduler, dispatch);
179            let root_task = executor.spawn(f(executor.clone()));
180            let _ = task_sender.send(root_task);
181            // After this drop, every strong reference to the runnable sender
182            // lives inside a spawned task or a user-held executor clone. The
183            // recv loop exits once all of those are gone.
184            drop(executor);
185
186            while let Ok(runnable) = runnable_receiver.recv() {
187                runnable.run();
188            }
189        })
190        .expect("failed to spawn dedicated thread");
191
192    task_receiver
193        .recv()
194        .expect("dedicated thread failed to produce root task")
195}
196
197#[derive(Copy, Clone, Debug, Eq, PartialEq, Ord, PartialOrd, Hash)]
198pub struct SessionId(u16);
199
200impl SessionId {
201    pub fn new(id: u16) -> Self {
202        SessionId(id)
203    }
204}
205
206pub struct Timer(oneshot::Receiver<()>);
207
208impl Timer {
209    pub fn new(rx: oneshot::Receiver<()>) -> Self {
210        Timer(rx)
211    }
212}
213
214impl Future for Timer {
215    type Output = ();
216
217    fn poll(mut self: Pin<&mut Self>, cx: &mut Context) -> Poll<()> {
218        match Pin::new(&mut self.0).poll(cx) {
219            Poll::Ready(_) => Poll::Ready(()),
220            Poll::Pending => Poll::Pending,
221        }
222    }
223}