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}