Skip to main content

guic_gpui_scheduler/
executor.rs

1use crate::{DedicatedTask, Instant, Priority, RunnableMeta, Scheduler, SessionId, Timer};
2use async_task::Runnable;
3use std::{
4    any::Any,
5    future::Future,
6    marker::PhantomData,
7    mem::ManuallyDrop,
8    panic::Location,
9    pin::Pin,
10    rc::Rc,
11    sync::Arc,
12    task::{Context, Poll},
13    thread::{self, ThreadId},
14    time::Duration,
15};
16
17/// A `!Send` executor pinned to a single session. Tasks spawned on it run in
18/// order on whichever thread drains the dispatch destination supplied at
19/// construction time — typically the main thread for the default session, or
20/// a dedicated OS thread for sessions created by `spawn_dedicated_thread`.
21#[derive(Clone)]
22pub struct LocalExecutor {
23    session_id: SessionId,
24    scheduler: Arc<dyn Scheduler>,
25    // Spawned tasks' schedule callbacks each hold an `Arc` clone of this
26    // closure, so the destination it captures stays alive as long as work
27    // could still land on it.
28    dispatch: Arc<dyn Fn(Runnable<RunnableMeta>) + Send + Sync>,
29    not_send: PhantomData<Rc<()>>,
30}
31
32impl LocalExecutor {
33    /// Constructs a local executor that runs spawned tasks by sending their
34    /// runnables through `dispatch`. The `scheduler` is retained for access to
35    /// clocks, timers, and other scheduler-level services.
36    ///
37    /// For the common case of routing runnables through
38    /// `Scheduler::schedule_local`, callers pass a closure that does exactly
39    /// that. `spawn_dedicated_thread` instead passes a closure that sends to
40    /// the dedicated thread's channel.
41    pub fn new(
42        session_id: SessionId,
43        scheduler: Arc<dyn Scheduler>,
44        dispatch: impl Fn(Runnable<RunnableMeta>) + Send + Sync + 'static,
45    ) -> Self {
46        Self {
47            session_id,
48            scheduler,
49            dispatch: Arc::new(dispatch),
50            not_send: PhantomData,
51        }
52    }
53
54    pub fn session_id(&self) -> SessionId {
55        self.session_id
56    }
57
58    pub fn scheduler(&self) -> &Arc<dyn Scheduler> {
59        &self.scheduler
60    }
61
62    #[track_caller]
63    pub fn spawn<F>(&self, future: F) -> Task<F::Output>
64    where
65        F: Future + 'static,
66        F::Output: 'static,
67    {
68        let dispatch = self.dispatch.clone();
69        let location = Location::caller();
70        let (runnable, task) = spawn_local_with_source_location(
71            future,
72            move |runnable| dispatch(runnable),
73            RunnableMeta {
74                location,
75                spawned: crate::SpawnTime(Instant::now()),
76            },
77        );
78        runnable.schedule();
79        Task(TaskState::Spawned(task))
80    }
81
82    /// Like [`Self::spawn`], but routes the task's runnables through the
83    /// given dispatch destination instead of this executor's own. The
84    /// destination must deliver runnables to this executor's thread: the
85    /// future is polled and dropped on the spawning thread.
86    #[track_caller]
87    pub fn spawn_with_dispatch<F>(
88        &self,
89        future: F,
90        dispatch: impl Fn(Runnable<RunnableMeta>) + Send + Sync + 'static,
91    ) -> Task<F::Output>
92    where
93        F: Future + 'static,
94        F::Output: 'static,
95    {
96        let location = Location::caller();
97        let (runnable, task) = spawn_local_with_source_location(
98            future,
99            dispatch,
100            RunnableMeta {
101                location,
102                spawned: crate::SpawnTime(Instant::now()),
103            },
104        );
105        runnable.schedule();
106        Task(TaskState::Spawned(task))
107    }
108
109    pub fn block_on<Fut: Future>(&self, future: Fut) -> Fut::Output {
110        use std::cell::Cell;
111
112        let output = Cell::new(None);
113        let future = async {
114            output.set(Some(future.await));
115        };
116        let mut future = std::pin::pin!(future);
117
118        self.scheduler
119            .block(Some(self.session_id), future.as_mut(), None);
120
121        output.take().expect("block_on future did not complete")
122    }
123
124    /// Block until the future completes or timeout occurs.
125    /// Returns Ok(output) if completed, Err(future) if timed out.
126    pub fn block_with_timeout<Fut: Future>(
127        &self,
128        timeout: Duration,
129        future: Fut,
130    ) -> Result<Fut::Output, impl Future<Output = Fut::Output> + use<Fut>> {
131        use std::cell::Cell;
132
133        let output = Cell::new(None);
134        let mut future = Box::pin(future);
135
136        {
137            let future_ref = &mut future;
138            let wrapper = async {
139                output.set(Some(future_ref.await));
140            };
141            let mut wrapper = std::pin::pin!(wrapper);
142
143            self.scheduler
144                .block(Some(self.session_id), wrapper.as_mut(), Some(timeout));
145        }
146
147        match output.take() {
148            Some(value) => Ok(value),
149            None => Err(future),
150        }
151    }
152
153    #[track_caller]
154    pub fn timer(&self, duration: Duration) -> Timer {
155        self.scheduler.timer(duration)
156    }
157
158    pub fn now(&self) -> Instant {
159        self.scheduler.clock().now()
160    }
161
162    /// Spawn a closure on a fresh session pinned to its own [`LocalExecutor`].
163    /// The closure runs on a new OS thread under `PlatformScheduler`, or on
164    /// the test scheduler's loop under `TestScheduler`.
165    ///
166    /// The returned `Task` represents the dedicated work: dropping it cancels
167    /// the dedicated closure, `.await`ing it yields the closure's return
168    /// value, `.detach()`ing it lets the dedicated work run independently of
169    /// the caller.
170    #[track_caller]
171    pub fn spawn_dedicated<F, Fut>(&self, f: F) -> Task<Fut::Output>
172    where
173        F: FnOnce(LocalExecutor) -> Fut + Send + 'static,
174        Fut: Future + 'static,
175        Fut::Output: Send + Sync + 'static,
176    {
177        self.scheduler
178            .clone()
179            .spawn_dedicated(box_dedicated(f))
180            .downcast::<Fut::Output>()
181    }
182}
183
184/// Boxes the user-supplied dedicated closure into the type-erased shape
185/// expected by [`Scheduler::spawn_dedicated`]. The user's `Fut::Output` is
186/// boxed as `Box<dyn Any + Send + Sync>` on the dedicated side and downcast
187/// back to `Fut::Output` by [`Task::downcast`] in the wrapper.
188fn box_dedicated<F, Fut>(f: F) -> DedicatedTask
189where
190    F: FnOnce(LocalExecutor) -> Fut + Send + 'static,
191    Fut: Future + 'static,
192    Fut::Output: Send + Sync + 'static,
193{
194    Box::new(move |executor| {
195        Box::pin(async move { Box::new(f(executor).await) as Box<dyn Any + Send + Sync> })
196    })
197}
198
199#[derive(Clone)]
200pub struct BackgroundExecutor {
201    scheduler: Arc<dyn Scheduler>,
202}
203
204impl BackgroundExecutor {
205    pub fn new(scheduler: Arc<dyn Scheduler>) -> Self {
206        Self { scheduler }
207    }
208
209    #[track_caller]
210    pub fn spawn<F>(&self, future: F) -> Task<F::Output>
211    where
212        F: Future + Send + 'static,
213        F::Output: Send + 'static,
214    {
215        self.spawn_with_priority(Priority::default(), future)
216    }
217
218    #[track_caller]
219    pub fn spawn_with_priority<F>(&self, priority: Priority, future: F) -> Task<F::Output>
220    where
221        F: Future + Send + 'static,
222        F::Output: Send + 'static,
223    {
224        let scheduler = Arc::downgrade(&self.scheduler);
225        let location = Location::caller();
226        let (runnable, task) = async_task::Builder::new()
227            .metadata(RunnableMeta {
228                location,
229                spawned: crate::SpawnTime(Instant::now()),
230            })
231            .spawn(
232                move |_| future,
233                move |runnable| {
234                    if let Some(scheduler) = scheduler.upgrade() {
235                        scheduler.schedule_background_with_priority(runnable, priority);
236                    }
237                },
238            );
239        runnable.schedule();
240        Task(TaskState::Spawned(task))
241    }
242
243    /// Spawns a future on a dedicated realtime thread for audio processing.
244    #[track_caller]
245    pub fn spawn_realtime<F>(&self, future: F) -> Task<F::Output>
246    where
247        F: Future + Send + 'static,
248        F::Output: Send + 'static,
249    {
250        let location = Location::caller();
251        let (tx, rx) = flume::bounded::<async_task::Runnable<RunnableMeta>>(1);
252
253        self.scheduler.spawn_realtime(Box::new(move || {
254            while let Ok(runnable) = rx.recv() {
255                runnable.run();
256            }
257        }));
258
259        let (runnable, task) = async_task::Builder::new()
260            .metadata(RunnableMeta {
261                location,
262                spawned: crate::SpawnTime(Instant::now()),
263            })
264            .spawn(
265                move |_| future,
266                move |runnable| {
267                    let _ = tx.send(runnable);
268                },
269            );
270        runnable.schedule();
271        Task(TaskState::Spawned(task))
272    }
273
274    #[track_caller]
275    pub fn timer(&self, duration: Duration) -> Timer {
276        self.scheduler.timer(duration)
277    }
278
279    pub fn now(&self) -> Instant {
280        self.scheduler.clock().now()
281    }
282
283    pub fn scheduler(&self) -> &Arc<dyn Scheduler> {
284        &self.scheduler
285    }
286
287    /// Spawn a closure on a fresh session pinned to its own [`LocalExecutor`].
288    /// The closure runs on a new OS thread under `PlatformScheduler`, or on
289    /// the test scheduler's loop under `TestScheduler`.
290    ///
291    /// The returned `Task` represents the dedicated work: dropping it cancels
292    /// the dedicated closure, `.await`ing it yields the closure's return
293    /// value, `.detach()`ing it lets the dedicated work run independently of
294    /// the caller.
295    #[track_caller]
296    pub fn spawn_dedicated<F, Fut>(&self, f: F) -> Task<Fut::Output>
297    where
298        F: FnOnce(LocalExecutor) -> Fut + Send + 'static,
299        Fut: Future + 'static,
300        Fut::Output: Send + Sync + 'static,
301    {
302        self.scheduler
303            .clone()
304            .spawn_dedicated(box_dedicated(f))
305            .downcast::<Fut::Output>()
306    }
307}
308
309/// Task is a primitive that allows work to happen in the background.
310///
311/// It implements [`Future`] so you can `.await` on it.
312///
313/// If you drop a task it will be cancelled immediately. Calling [`Task::detach`] allows
314/// the task to continue running, but with no way to return a value.
315#[must_use]
316pub struct Task<T>(TaskState<T>);
317
318enum TaskState<T> {
319    /// A task that is ready to return a value
320    Ready(Option<T>),
321
322    /// A task that is currently running.
323    Spawned(async_task::Task<T, RunnableMeta>),
324
325    /// A typed view of a [`Task<Box<dyn Any + Send + Sync>>`] obtained via
326    /// [`Task::downcast`]. The inner task drives the actual work; the
327    /// downcast layer just unwraps the `Box<dyn Any + Send + Sync>` on poll.
328    Downcast {
329        inner: Box<Task<Box<dyn Any + Send + Sync>>>,
330        marker: PhantomData<fn() -> T>,
331    },
332}
333
334impl<T> Task<T> {
335    /// Creates a new task that will resolve with the value
336    pub fn ready(val: T) -> Self {
337        Task(TaskState::Ready(Some(val)))
338    }
339
340    /// Creates a Task from an async_task::Task
341    pub fn from_async_task(task: async_task::Task<T, RunnableMeta>) -> Self {
342        Task(TaskState::Spawned(task))
343    }
344
345    pub fn is_ready(&self) -> bool {
346        match &self.0 {
347            TaskState::Ready(_) => true,
348            TaskState::Spawned(task) => task.is_finished(),
349            TaskState::Downcast { inner, .. } => inner.is_ready(),
350        }
351    }
352
353    /// Detaching a task runs it to completion in the background
354    pub fn detach(self) {
355        match self {
356            Task(TaskState::Ready(_)) => {}
357            Task(TaskState::Spawned(task)) => task.detach(),
358            Task(TaskState::Downcast { inner, .. }) => inner.detach(),
359        }
360    }
361
362    /// Converts this task into a fallible task that returns `Option<T>`.
363    pub fn fallible(self) -> FallibleTask<T> {
364        FallibleTask(match self.0 {
365            TaskState::Ready(val) => FallibleTaskState::Ready(val),
366            TaskState::Spawned(task) => FallibleTaskState::Spawned(task.fallible()),
367            TaskState::Downcast { inner, .. } => FallibleTaskState::Downcast {
368                inner: Box::new(inner.fallible()),
369                marker: PhantomData,
370            },
371        })
372    }
373}
374
375impl Task<Box<dyn Any + Send + Sync>> {
376    /// Reinterprets the boxed output as a concrete `T` via downcast on
377    /// completion. Used by [`LocalExecutor::spawn_dedicated`] and
378    /// [`BackgroundExecutor::spawn_dedicated`] to recover the user closure's
379    /// `Fut::Output` from the dyn-safe [`Scheduler::spawn_dedicated`].
380    ///
381    /// Panics on poll if the inner output is not in fact a `T` -- a logic
382    /// error in whatever produced the inner task, since the downcast type is
383    /// chosen by the caller of `downcast`.
384    pub fn downcast<T: Send + Sync + 'static>(self) -> Task<T> {
385        Task(TaskState::Downcast {
386            inner: Box::new(self),
387            marker: PhantomData,
388        })
389    }
390}
391
392impl<T> std::fmt::Debug for Task<T> {
393    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
394        match &self.0 {
395            TaskState::Ready(_) => f.debug_tuple("Task::Ready").finish(),
396            TaskState::Spawned(task) => f.debug_tuple("Task::Spawned").field(task).finish(),
397            TaskState::Downcast { inner, .. } => {
398                f.debug_tuple("Task::Downcast").field(inner).finish()
399            }
400        }
401    }
402}
403
404/// A task that returns `Option<T>` instead of panicking when cancelled.
405#[must_use]
406pub struct FallibleTask<T>(FallibleTaskState<T>);
407
408enum FallibleTaskState<T> {
409    /// A task that is ready to return a value
410    Ready(Option<T>),
411
412    /// A task that is currently running (wraps async_task::FallibleTask).
413    Spawned(async_task::FallibleTask<T, RunnableMeta>),
414
415    /// Mirror of [`TaskState::Downcast`] for fallible tasks.
416    Downcast {
417        inner: Box<FallibleTask<Box<dyn Any + Send + Sync>>>,
418        marker: PhantomData<fn() -> T>,
419    },
420}
421
422impl<T> FallibleTask<T> {
423    /// Creates a new fallible task that will resolve with the value.
424    pub fn ready(val: T) -> Self {
425        FallibleTask(FallibleTaskState::Ready(Some(val)))
426    }
427
428    /// Detaching a task runs it to completion in the background.
429    pub fn detach(self) {
430        match self.0 {
431            FallibleTaskState::Ready(_) => {}
432            FallibleTaskState::Spawned(task) => task.detach(),
433            FallibleTaskState::Downcast { inner, .. } => inner.detach(),
434        }
435    }
436}
437
438impl<T: 'static> Future for FallibleTask<T> {
439    type Output = Option<T>;
440
441    fn poll(self: Pin<&mut Self>, cx: &mut Context) -> Poll<Self::Output> {
442        match unsafe { self.get_unchecked_mut() } {
443            FallibleTask(FallibleTaskState::Ready(val)) => Poll::Ready(val.take()),
444            FallibleTask(FallibleTaskState::Spawned(task)) => Pin::new(task).poll(cx),
445            FallibleTask(FallibleTaskState::Downcast { inner, .. }) => {
446                match Pin::new(inner.as_mut()).poll(cx) {
447                    Poll::Ready(Some(boxed_any)) => Poll::Ready(Some(
448                        *boxed_any
449                            .downcast::<T>()
450                            .expect("FallibleTask::poll: downcast type mismatch"),
451                    )),
452                    Poll::Ready(None) => Poll::Ready(None),
453                    Poll::Pending => Poll::Pending,
454                }
455            }
456        }
457    }
458}
459
460impl<T> std::fmt::Debug for FallibleTask<T> {
461    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
462        match &self.0 {
463            FallibleTaskState::Ready(_) => f.debug_tuple("FallibleTask::Ready").finish(),
464            FallibleTaskState::Spawned(task) => {
465                f.debug_tuple("FallibleTask::Spawned").field(task).finish()
466            }
467            FallibleTaskState::Downcast { inner, .. } => f
468                .debug_tuple("FallibleTask::Downcast")
469                .field(inner)
470                .finish(),
471        }
472    }
473}
474
475impl<T: 'static> Future for Task<T> {
476    type Output = T;
477
478    fn poll(self: Pin<&mut Self>, cx: &mut Context) -> Poll<Self::Output> {
479        match unsafe { self.get_unchecked_mut() } {
480            Task(TaskState::Ready(val)) => Poll::Ready(val.take().unwrap()),
481            Task(TaskState::Spawned(task)) => Pin::new(task).poll(cx),
482            Task(TaskState::Downcast { inner, .. }) => match Pin::new(inner.as_mut()).poll(cx) {
483                Poll::Ready(boxed_any) => Poll::Ready(
484                    *boxed_any
485                        .downcast::<T>()
486                        .expect("Task::poll: downcast type mismatch"),
487                ),
488                Poll::Pending => Poll::Pending,
489            },
490        }
491    }
492}
493
494/// Variant of `async_task::spawn_local` that includes the source location of the spawn in panics.
495#[track_caller]
496fn spawn_local_with_source_location<Fut, S>(
497    future: Fut,
498    schedule: S,
499    metadata: RunnableMeta,
500) -> (
501    async_task::Runnable<RunnableMeta>,
502    async_task::Task<Fut::Output, RunnableMeta>,
503)
504where
505    Fut: Future + 'static,
506    Fut::Output: 'static,
507    S: async_task::Schedule<RunnableMeta> + Send + Sync + 'static,
508{
509    #[inline]
510    fn thread_id() -> ThreadId {
511        std::thread_local! {
512            static ID: ThreadId = thread::current().id();
513        }
514        ID.try_with(|id| *id)
515            .unwrap_or_else(|_| thread::current().id())
516    }
517
518    struct Checked<F> {
519        id: ThreadId,
520        inner: ManuallyDrop<F>,
521        location: &'static Location<'static>,
522    }
523
524    impl<F> Drop for Checked<F> {
525        fn drop(&mut self) {
526            assert_eq!(
527                self.id,
528                thread_id(),
529                "local task dropped by a thread that didn't spawn it. Task spawned at {}",
530                self.location
531            );
532            // SAFETY: `inner` is wrapped in `ManuallyDrop`, so this is the only
533            // place it is dropped. The thread check above ensures local futures
534            // are dropped on the thread that created them.
535            unsafe { ManuallyDrop::drop(&mut self.inner) };
536        }
537    }
538
539    impl<F: Future> Future for Checked<F> {
540        type Output = F::Output;
541
542        fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
543            // SAFETY: We don't move any fields out of `self`; this mutable
544            // reference is only used to check metadata and to project the pin to
545            // `inner` below.
546            let this = unsafe { self.get_unchecked_mut() };
547            assert!(
548                this.id == thread_id(),
549                "local task polled by a thread that didn't spawn it. Task spawned at {}",
550                this.location
551            );
552            // SAFETY: `inner` is structurally pinned by `Checked`; after
553            // `Checked` is pinned, `inner` is never moved. The thread check
554            // above ensures the local future is only polled by its spawning
555            // thread.
556            unsafe { Pin::new_unchecked(&mut *this.inner).poll(cx) }
557        }
558    }
559
560    let location = metadata.location;
561
562    let future = move |_| Checked {
563        id: thread_id(),
564        inner: ManuallyDrop::new(future),
565        location,
566    };
567
568    let builder = async_task::Builder::new().metadata(metadata);
569    // SAFETY: `Checked` enforces the invariants required by `spawn_unchecked`:
570    // the non-`Send` future is only polled and dropped on the thread that
571    // spawned it.
572    unsafe { builder.spawn_unchecked(future, schedule) }
573}