1use crate::{App, PlatformDispatcher, PlatformScheduler};
2use futures::channel::mpsc;
3use futures::prelude::*;
4use gpui_util::TryFutureExt;
5use scheduler::Instant;
6use scheduler::Scheduler;
7use std::{
8 fmt::Debug, future::Future, marker::PhantomData, mem, pin::Pin, rc::Rc, sync::Arc,
9 time::Duration,
10};
11
12pub use scheduler::{FallibleTask, ForegroundExecutor as SchedulerForegroundExecutor, Priority};
13
14/// A pointer to the executor that is currently running,
15/// for spawning background tasks.
16#[derive(Clone)]
17pub struct BackgroundExecutor {
18 inner: scheduler::BackgroundExecutor,
19 dispatcher: Arc<dyn PlatformDispatcher>,
20}
21
22/// A pointer to the executor that is currently running,
23/// for spawning tasks on the main thread.
24#[derive(Clone)]
25pub struct ForegroundExecutor {
26 inner: scheduler::ForegroundExecutor,
27 dispatcher: Arc<dyn PlatformDispatcher>,
28 not_send: PhantomData<Rc<()>>,
29}
30
31/// Task is a primitive that allows work to happen in the background.
32///
33/// It implements [`Future`] so you can `.await` on it.
34///
35/// If you drop a task it will be cancelled immediately. Calling [`Task::detach`] allows
36/// the task to continue running, but with no way to return a value.
37#[must_use]
38#[derive(Debug)]
39pub struct Task<T>(scheduler::Task<T>);
40
41impl<T> Task<T> {
42 /// Creates a new task that will resolve with the value.
43 pub fn ready(val: T) -> Self {
44 Task(scheduler::Task::ready(val))
45 }
46
47 /// Returns true if the task has completed or was created with `Task::ready`.
48 pub fn is_ready(&self) -> bool {
49 self.0.is_ready()
50 }
51
52 /// Detaching a task runs it to completion in the background.
53 pub fn detach(self) {
54 self.0.detach()
55 }
56
57 /// Wraps a scheduler::Task.
58 pub fn from_scheduler(task: scheduler::Task<T>) -> Self {
59 Task(task)
60 }
61
62 /// Converts this task into a fallible task that returns `Option<T>`.
63 ///
64 /// Unlike the standard `Task<T>`, a [`FallibleTask`] will return `None`
65 /// if the task was cancelled.
66 ///
67 /// # Example
68 ///
69 /// ```ignore
70 /// // Background task that gracefully handles cancellation:
71 /// cx.background_spawn(async move {
72 /// let result = foreground_task.fallible().await;
73 /// if let Some(value) = result {
74 /// // Process the value
75 /// }
76 /// // If None, task was cancelled - just exit gracefully
77 /// }).detach();
78 /// ```
79 pub fn fallible(self) -> FallibleTask<T> {
80 self.0.fallible()
81 }
82}
83
84impl<T, E> Task<Result<T, E>>
85where
86 T: 'static,
87 E: 'static + Debug,
88{
89 /// Run the task to completion in the background and log any errors that occur.
90 #[track_caller]
91 pub fn detach_and_log_err(self, cx: &App) {
92 let location = core::panic::Location::caller();
93 cx.foreground_executor()
94 .spawn(self.log_tracked_err(*location))
95 .detach();
96 }
97}
98
99impl<T> std::future::Future for Task<T> {
100 type Output = T;
101
102 fn poll(
103 self: std::pin::Pin<&mut Self>,
104 cx: &mut std::task::Context<'_>,
105 ) -> std::task::Poll<Self::Output> {
106 // SAFETY: Task is a repr(transparent) wrapper around scheduler::Task,
107 // and we're just projecting the pin through to the inner task.
108 let inner = unsafe { self.map_unchecked_mut(|t| &mut t.0) };
109 inner.poll(cx)
110 }
111}
112
113impl BackgroundExecutor {
114 /// Creates a new BackgroundExecutor from the given PlatformDispatcher.
115 pub fn new(dispatcher: Arc<dyn PlatformDispatcher>) -> Self {
116 #[cfg(any(test, feature = "test-support"))]
117 let scheduler: Arc<dyn Scheduler> = if let Some(test_dispatcher) = dispatcher.as_test() {
118 test_dispatcher.scheduler().clone()
119 } else {
120 Arc::new(PlatformScheduler::new(dispatcher.clone()))
121 };
122
123 #[cfg(not(any(test, feature = "test-support")))]
124 let scheduler: Arc<dyn Scheduler> = Arc::new(PlatformScheduler::new(dispatcher.clone()));
125
126 Self {
127 inner: scheduler::BackgroundExecutor::new(scheduler),
128 dispatcher,
129 }
130 }
131
132 /// Returns the underlying scheduler::BackgroundExecutor.
133 ///
134 /// This is used by Ex to pass the executor to thread/worktree code.
135 pub fn scheduler_executor(&self) -> scheduler::BackgroundExecutor {
136 self.inner.clone()
137 }
138
139 /// Enqueues the given future to be run to completion on a background thread.
140 #[track_caller]
141 pub fn spawn<R>(&self, future: impl Future<Output = R> + Send + 'static) -> Task<R>
142 where
143 R: Send + 'static,
144 {
145 self.spawn_with_priority(Priority::default(), future.boxed())
146 }
147
148 /// Enqueues the given future to be run to completion on a background thread with the given priority.
149 ///
150 /// When `Priority::RealtimeAudio` is used, the task runs on a dedicated thread with
151 /// realtime scheduling priority, suitable for audio processing.
152 #[track_caller]
153 pub fn spawn_with_priority<R>(
154 &self,
155 priority: Priority,
156 future: impl Future<Output = R> + Send + 'static,
157 ) -> Task<R>
158 where
159 R: Send + 'static,
160 {
161 if priority == Priority::RealtimeAudio {
162 Task::from_scheduler(self.inner.spawn_realtime(future))
163 } else {
164 Task::from_scheduler(self.inner.spawn_with_priority(priority, future))
165 }
166 }
167
168 /// Enqueues the given future to be run to completion on a background thread and blocking the current task on it.
169 ///
170 /// This allows to spawn background work that borrows from its scope. Note that the supplied future will run to
171 /// completion before the current task is resumed, even if the current task is slated for cancellation.
172 pub async fn await_on_background<R>(&self, future: impl Future<Output = R> + Send) -> R
173 where
174 R: Send,
175 {
176 use crate::RunnableMeta;
177 use parking_lot::{Condvar, Mutex};
178
179 struct NotifyOnDrop<'a>(&'a (Condvar, Mutex<bool>));
180
181 impl Drop for NotifyOnDrop<'_> {
182 fn drop(&mut self) {
183 *self.0.1.lock() = true;
184 self.0.0.notify_all();
185 }
186 }
187
188 struct WaitOnDrop<'a>(&'a (Condvar, Mutex<bool>));
189
190 impl Drop for WaitOnDrop<'_> {
191 fn drop(&mut self) {
192 let mut done = self.0.1.lock();
193 if !*done {
194 self.0.0.wait(&mut done);
195 }
196 }
197 }
198
199 let dispatcher = self.dispatcher.clone();
200 let location = core::panic::Location::caller();
201
202 let pair = &(Condvar::new(), Mutex::new(false));
203 let _wait_guard = WaitOnDrop(pair);
204
205 let (runnable, task) = unsafe {
206 async_task::Builder::new()
207 .metadata(RunnableMeta { location })
208 .spawn_unchecked(
209 move |_| async {
210 let _notify_guard = NotifyOnDrop(pair);
211 future.await
212 },
213 move |runnable| {
214 dispatcher.dispatch(runnable, Priority::default());
215 },
216 )
217 };
218 runnable.schedule();
219 task.await
220 }
221
222 /// Scoped lets you start a number of tasks and waits
223 /// for all of them to complete before returning.
224 pub async fn scoped<'scope, F>(&self, scheduler: F)
225 where
226 F: FnOnce(&mut Scope<'scope>),
227 {
228 let mut scope = Scope::new(self.clone(), Priority::default());
229 (scheduler)(&mut scope);
230 let spawned = mem::take(&mut scope.futures)
231 .into_iter()
232 .map(|f| self.spawn_with_priority(scope.priority, f))
233 .collect::<Vec<_>>();
234 for task in spawned {
235 task.await;
236 }
237 }
238
239 /// Scoped lets you start a number of tasks and waits
240 /// for all of them to complete before returning.
241 pub async fn scoped_priority<'scope, F>(&self, priority: Priority, scheduler: F)
242 where
243 F: FnOnce(&mut Scope<'scope>),
244 {
245 let mut scope = Scope::new(self.clone(), priority);
246 (scheduler)(&mut scope);
247 let spawned = mem::take(&mut scope.futures)
248 .into_iter()
249 .map(|f| self.spawn_with_priority(scope.priority, f))
250 .collect::<Vec<_>>();
251 for task in spawned {
252 task.await;
253 }
254 }
255
256 /// Get the current time.
257 ///
258 /// Calling this instead of `std::time::Instant::now` allows the use
259 /// of fake timers in tests.
260 pub fn now(&self) -> Instant {
261 self.inner.scheduler().clock().now()
262 }
263
264 /// Returns a task that will complete after the given duration.
265 /// Depending on other concurrent tasks the elapsed duration may be longer
266 /// than requested.
267 #[track_caller]
268 pub fn timer(&self, duration: Duration) -> Task<()> {
269 if duration.is_zero() {
270 return Task::ready(());
271 }
272 self.spawn(self.inner.scheduler().timer(duration))
273 }
274
275 /// In tests, run an arbitrary number of tasks (determined by the SEED environment variable)
276 #[cfg(any(test, feature = "test-support"))]
277 pub fn simulate_random_delay(&self) -> impl Future<Output = ()> + use<> {
278 self.dispatcher.as_test().unwrap().simulate_random_delay()
279 }
280
281 /// In tests, move time forward. This does not run any tasks, but does make `timer`s ready.
282 #[cfg(any(test, feature = "test-support"))]
283 pub fn advance_clock(&self, duration: Duration) {
284 self.dispatcher.as_test().unwrap().advance_clock(duration)
285 }
286
287 /// In tests, run one task.
288 #[cfg(any(test, feature = "test-support"))]
289 pub fn tick(&self) -> bool {
290 self.dispatcher.as_test().unwrap().scheduler().tick()
291 }
292
293 /// In tests, run tasks until the scheduler would park.
294 ///
295 /// Under the scheduler-backed test dispatcher, `tick()` will not advance the clock, so a pending
296 /// timer can keep `has_pending_tasks()` true even after all currently-runnable tasks have been
297 /// drained. To preserve the historical semantics that tests relied on (drain all work that can
298 /// make progress), we advance the clock to the next timer when no runnable tasks remain.
299 #[cfg(any(test, feature = "test-support"))]
300 pub fn run_until_parked(&self) {
301 let scheduler = self.dispatcher.as_test().unwrap().scheduler();
302 scheduler.run();
303 }
304
305 /// In tests, prevents `run_until_parked` from panicking if there are outstanding tasks.
306 #[cfg(any(test, feature = "test-support"))]
307 pub fn allow_parking(&self) {
308 self.dispatcher
309 .as_test()
310 .unwrap()
311 .scheduler()
312 .allow_parking();
313
314 if std::env::var("GPUI_RUN_UNTIL_PARKED_LOG").ok().as_deref() == Some("1") {
315 log::warn!("[gpui::executor] allow_parking: enabled");
316 }
317 }
318
319 /// Sets the range of ticks to run before timing out in block_on.
320 #[cfg(any(test, feature = "test-support"))]
321 pub fn set_block_on_ticks(&self, range: std::ops::RangeInclusive<usize>) {
322 self.dispatcher
323 .as_test()
324 .unwrap()
325 .scheduler()
326 .set_timeout_ticks(range);
327 }
328
329 /// Undoes the effect of [`Self::allow_parking`].
330 #[cfg(any(test, feature = "test-support"))]
331 pub fn forbid_parking(&self) {
332 self.dispatcher
333 .as_test()
334 .unwrap()
335 .scheduler()
336 .forbid_parking();
337 }
338
339 /// In tests, returns the rng used by the dispatcher.
340 #[cfg(any(test, feature = "test-support"))]
341 pub fn rng(&self) -> scheduler::SharedRng {
342 self.dispatcher.as_test().unwrap().scheduler().rng()
343 }
344
345 /// How many CPUs are available to the dispatcher.
346 pub fn num_cpus(&self) -> usize {
347 #[cfg(any(test, feature = "test-support"))]
348 if let Some(test) = self.dispatcher.as_test() {
349 return test.num_cpus_override().unwrap_or(4);
350 }
351 num_cpus::get()
352 }
353
354 /// Override the number of CPUs reported by this executor in tests.
355 /// Panics if not called on a test executor.
356 #[cfg(any(test, feature = "test-support"))]
357 pub fn set_num_cpus(&self, count: usize) {
358 self.dispatcher
359 .as_test()
360 .expect("set_num_cpus can only be called on a test executor")
361 .set_num_cpus(count);
362 }
363
364 /// Whether we're on the main thread.
365 pub fn is_main_thread(&self) -> bool {
366 self.dispatcher.is_main_thread()
367 }
368
369 #[doc(hidden)]
370 pub fn dispatcher(&self) -> &Arc<dyn PlatformDispatcher> {
371 &self.dispatcher
372 }
373}
374
375impl ForegroundExecutor {
376 /// Creates a new ForegroundExecutor from the given PlatformDispatcher.
377 pub fn new(dispatcher: Arc<dyn PlatformDispatcher>) -> Self {
378 #[cfg(any(test, feature = "test-support"))]
379 let (scheduler, session_id): (Arc<dyn Scheduler>, _) =
380 if let Some(test_dispatcher) = dispatcher.as_test() {
381 (
382 test_dispatcher.scheduler().clone(),
383 test_dispatcher.session_id(),
384 )
385 } else {
386 let platform_scheduler = Arc::new(PlatformScheduler::new(dispatcher.clone()));
387 let session_id = platform_scheduler.allocate_session_id();
388 (platform_scheduler, session_id)
389 };
390
391 #[cfg(not(any(test, feature = "test-support")))]
392 let (scheduler, session_id): (Arc<dyn Scheduler>, _) = {
393 let platform_scheduler = Arc::new(PlatformScheduler::new(dispatcher.clone()));
394 let session_id = platform_scheduler.allocate_session_id();
395 (platform_scheduler, session_id)
396 };
397
398 let inner = scheduler::ForegroundExecutor::new(session_id, scheduler);
399
400 Self {
401 inner,
402 dispatcher,
403 not_send: PhantomData,
404 }
405 }
406
407 /// Enqueues the given Task to run on the main thread.
408 #[track_caller]
409 pub fn spawn<R>(&self, future: impl Future<Output = R> + 'static) -> Task<R>
410 where
411 R: 'static,
412 {
413 Task::from_scheduler(self.inner.spawn(future.boxed_local()))
414 }
415
416 /// Enqueues the given Task to run on the main thread with the given priority.
417 #[track_caller]
418 pub fn spawn_with_priority<R>(
419 &self,
420 _priority: Priority,
421 future: impl Future<Output = R> + 'static,
422 ) -> Task<R>
423 where
424 R: 'static,
425 {
426 // Priority is ignored for foreground tasks - they run in order on the main thread
427 Task::from_scheduler(self.inner.spawn(future))
428 }
429
430 /// Used by the test harness to run an async test in a synchronous fashion.
431 #[cfg(any(test, feature = "test-support"))]
432 #[track_caller]
433 pub fn block_test<R>(&self, future: impl Future<Output = R>) -> R {
434 use std::cell::Cell;
435
436 let scheduler = self.inner.scheduler();
437
438 let output = Cell::new(None);
439 let future = async {
440 output.set(Some(future.await));
441 };
442 let mut future = std::pin::pin!(future);
443
444 // In async GPUI tests, we must allow foreground tasks scheduled by the test itself
445 // (which are associated with the test session) to make progress while we block.
446 // Otherwise, awaiting futures that depend on same-session foreground work can deadlock.
447 scheduler.block(None, future.as_mut(), None);
448
449 output.take().expect("block_test future did not complete")
450 }
451
452 /// Block the current thread until the given future resolves.
453 /// Consider using `block_with_timeout` instead.
454 pub fn block_on<R>(&self, future: impl Future<Output = R>) -> R {
455 self.inner.block_on(future)
456 }
457
458 /// Block the current thread until the given future resolves or the timeout elapses.
459 pub fn block_with_timeout<R, Fut: Future<Output = R>>(
460 &self,
461 duration: Duration,
462 future: Fut,
463 ) -> Result<R, impl Future<Output = R> + use<R, Fut>> {
464 self.inner.block_with_timeout(duration, future)
465 }
466
467 #[doc(hidden)]
468 pub fn dispatcher(&self) -> &Arc<dyn PlatformDispatcher> {
469 &self.dispatcher
470 }
471
472 #[doc(hidden)]
473 pub fn scheduler_executor(&self) -> SchedulerForegroundExecutor {
474 self.inner.clone()
475 }
476}
477
478/// Scope manages a set of tasks that are enqueued and waited on together. See [`BackgroundExecutor::scoped`].
479pub struct Scope<'a> {
480 executor: BackgroundExecutor,
481 priority: Priority,
482 futures: Vec<Pin<Box<dyn Future<Output = ()> + Send + 'static>>>,
483 tx: Option<mpsc::Sender<()>>,
484 rx: mpsc::Receiver<()>,
485 lifetime: PhantomData<&'a ()>,
486}
487
488impl<'a> Scope<'a> {
489 fn new(executor: BackgroundExecutor, priority: Priority) -> Self {
490 let (tx, rx) = mpsc::channel(1);
491 Self {
492 executor,
493 priority,
494 tx: Some(tx),
495 rx,
496 futures: Default::default(),
497 lifetime: PhantomData,
498 }
499 }
500
501 /// How many CPUs are available to the dispatcher.
502 pub fn num_cpus(&self) -> usize {
503 self.executor.num_cpus()
504 }
505
506 /// Spawn a future into this scope.
507 #[track_caller]
508 pub fn spawn<F>(&mut self, f: F)
509 where
510 F: Future<Output = ()> + Send + 'a,
511 {
512 let tx = self.tx.clone().unwrap();
513
514 // SAFETY: The 'a lifetime is guaranteed to outlive any of these futures because
515 // dropping this `Scope` blocks until all of the futures have resolved.
516 let f = unsafe {
517 mem::transmute::<
518 Pin<Box<dyn Future<Output = ()> + Send + 'a>>,
519 Pin<Box<dyn Future<Output = ()> + Send + 'static>>,
520 >(Box::pin(async move {
521 f.await;
522 drop(tx);
523 }))
524 };
525 self.futures.push(f);
526 }
527}
528
529impl Drop for Scope<'_> {
530 fn drop(&mut self) {
531 self.tx.take().unwrap();
532
533 // Wait until the channel is closed, which means that all of the spawned
534 // futures have resolved.
535 let future = async {
536 self.rx.next().await;
537 };
538 let mut future = std::pin::pin!(future);
539 self.executor
540 .inner
541 .scheduler()
542 .block(None, future.as_mut(), None);
543 }
544}
545
546#[cfg(test)]
547mod test {
548 use super::*;
549 use crate::{App, TestDispatcher, TestPlatform};
550 use std::cell::RefCell;
551
552 /// Helper to create test infrastructure.
553 /// Returns (dispatcher, background_executor, app).
554 fn create_test_app() -> (TestDispatcher, BackgroundExecutor, Rc<crate::AppCell>) {
555 let dispatcher = TestDispatcher::new(0);
556 let arc_dispatcher = Arc::new(dispatcher.clone());
557 let background_executor = BackgroundExecutor::new(arc_dispatcher.clone());
558 let foreground_executor = ForegroundExecutor::new(arc_dispatcher);
559
560 let platform = TestPlatform::new(background_executor.clone(), foreground_executor);
561 let asset_source = Arc::new(());
562 let http_client = http_client::FakeHttpClient::with_404_response();
563
564 let app = App::new_app(platform, asset_source, http_client);
565 (dispatcher, background_executor, app)
566 }
567
568 #[test]
569 fn sanity_test_tasks_run() {
570 let (dispatcher, _background_executor, app) = create_test_app();
571 let foreground_executor = app.borrow().foreground_executor.clone();
572
573 let task_ran = Rc::new(RefCell::new(false));
574
575 foreground_executor
576 .spawn({
577 let task_ran = Rc::clone(&task_ran);
578 async move {
579 *task_ran.borrow_mut() = true;
580 }
581 })
582 .detach();
583
584 // Run dispatcher while app is still alive
585 dispatcher.run_until_parked();
586
587 // Task should have run
588 assert!(
589 *task_ran.borrow(),
590 "Task should run normally when app is alive"
591 );
592 }
593}