Struct BackgroundExecutor 

pub struct BackgroundExecutor { /* private fields */ }

Runs Send futures on GPUI’s background executor.

Get one from App::background_executor or crate::AsyncApp::background_executor. Its futures must be Send and 'static, so they cannot borrow entities or contexts. Pass in plain data and return plain data. Native backends use worker threads; a single-threaded web build runs these futures on the browser’s main thread. See executors.

Implementations

impl BackgroundExecutor

pub fn new(dispatcher: Arc<dyn PlatformDispatcher>) -> Self

Creates an executor that sends its work through dispatcher.

Platform code creates the executor. Apps get one from App::background_executor.

pub fn scheduler_executor(&self) -> BackgroundExecutor

Returns the underlying scheduler executor, for code that takes one directly.

pub fn spawn_dedicated<F, Fut>(&self, f: F) -> Task<Fut::Output>

where F: FnOnce(SchedulerLocalExecutor) -> Fut + Send + 'static, Fut: Future + 'static, Fut::Output: Send + Sync + 'static,

Runs the future that f returns on a thread of its own, and returns a task for its result.

Use this instead of BackgroundExecutor::spawn for work whose polls need more stack than the shared background threads provide. A dedicated thread gets the standard library’s default stack of 2 MiB. Dropping the task cancels the work, as it does for any task.

pub fn prevent_app_nap(&self, reason: &str) -> ActivityGuard

Prevents App Nap-style throttling while the returned guard is held.

This does not prevent the system from entering idle sleep.

pub fn spawn<R>( &self, future: impl Future<Output = R> + Send + 'static, ) -> Task<R>

where R: Send + 'static,

Schedules future on this executor and returns a task for its result.

On native targets, use this for computation or blocking I/O that should leave the main thread free. On a single-threaded web build it uses the main thread, so each poll must remain short. The future must be Send and 'static. To get the result on the main thread, await the task from a foreground future. Dropping the task cancels the future.

Examples

use gpui::TestApp;

let app = TestApp::new();
let task = app.background_executor().spawn(async { 6 * 7 });
assert_eq!(app.foreground_executor().block_test(task), 42);

pub fn spawn_with_priority<R>( &self, priority: Priority, future: impl Future<Output = R> + Send + 'static, ) -> Task<R>

where R: Send + 'static,

Like BackgroundExecutor::spawn, but with a Priority.

Higher priorities are more likely to run first, but the order isn’t guaranteed. Priority::RealtimeAudio runs the future on a dedicated thread with realtime scheduling. Use it only for audio work.

pub async fn scoped<'scope, F>(&self, scheduler: F)

where F: FnOnce(&mut Scope<'scope>),

Runs futures that may borrow from the caller in parallel, and waits for all of them to finish.

scheduler receives a Scope and spawns the futures on it. Unlike BackgroundExecutor::spawn, those futures needn’t be 'static, because the returned future doesn’t complete until they have. Dropping the returned future cancels the futures, and blocks until they are destroyed. If scheduler panics, the futures that haven’t started are dropped, and the panic unwinds without hanging.

Examples

use std::sync::atomic::{AtomicUsize, Ordering};
use gpui::TestApp;

let app = TestApp::new();
let total = AtomicUsize::new(0);
app.foreground_executor().block_test(app.background_executor().scoped(|scope| {
    for n in 1..=3 {
        let total = &total;
        scope.spawn(async move {
            total.fetch_add(n, Ordering::SeqCst);
        });
    }
}));
assert_eq!(total.into_inner(), 6);

pub async fn scoped_priority<'scope, F>(&self, priority: Priority, scheduler: F)

where F: FnOnce(&mut Scope<'scope>),

Like BackgroundExecutor::scoped, but runs every future in the scope at priority.

pub fn now(&self) -> Instant

Returns the current time.

Use this in place of std::time::Instant::now so that tests can control time. In tests it reads the simulated clock, which moves only when the test advances it.

pub fn timer(&self, duration: Duration) -> Task<()>

Returns a task that completes after duration.

Await it to delay work or to repeat it on an interval. In tests, time moves only when the test calls BackgroundExecutor::advance_clock. Other work can delay the wake-up, so the real wait can be longer than duration. A zero duration returns a task that is already complete.

Examples

use std::time::Duration;
use gpui::TestApp;

let app = TestApp::new();
let timer = app.background_executor().timer(Duration::from_millis(500));
app.advance_clock(Duration::from_millis(500));
assert!(timer.is_ready());

pub fn simulate_random_delay(&self) -> impl Future<Output = ()> + use<>

Yields a random number of times, allowing other ready tasks to run between steps.

Await it between steps of a test to shake out ordering bugs. Only available in tests.

Panics

Panics if this executor isn’t a test executor.

pub fn advance_clock(&self, duration: Duration)

Moves the simulated clock forward by duration.

Ready tasks run as the clock passes each timer, in time order, so a task that waits on a timer resumes at the right moment. When the call returns, the clock reads its earlier value plus duration. Only available in tests.

Panics

Panics if this executor isn’t a test executor.

pub fn tick(&self) -> bool

Runs one unit of ready work in tests.

Returns true if it ran a task or fired a timer, and false if there was nothing to do. Only available in tests.

Panics

Panics if this executor isn’t a test executor.

pub fn run_until_parked(&self)

Runs ready tasks in tests until none can make progress.

This doesn’t move the simulated clock. A timer that hasn’t expired stays pending, until BackgroundExecutor::advance_clock moves time past it. Only available in tests.

pub fn allow_parking(&self)

Lets blocking waits in tests sleep in real time when no test work can make progress.

By default, a blocking call that cannot progress panics. With parking allowed, it waits in real time instead, and the test fails if the wait lasts 15 seconds. Use this for tests that wait on real I/O. Undo it with BackgroundExecutor::forbid_parking.

pub fn set_block_on_ticks(&self, range: RangeInclusive<usize>)

Sets the range that the tick budget of a ForegroundExecutor::block_with_timeout call is drawn from, in tests.

The default is 1 to 1000 ticks. Only available in tests.

pub fn forbid_parking(&self)

Undoes BackgroundExecutor::allow_parking, so a blocking call that can’t progress panics again. Only available in tests.

pub fn rng(&self) -> SharedRng

Returns the seeded random number generator that the test scheduler uses.

Draw from it when a test makes its own random choices, so that the choices repeat with the same SEED. Only available in tests.

pub fn num_cpus(&self) -> usize

Returns the number of CPUs the dispatcher reports.

In tests this is 4 unless it was changed with BackgroundExecutor::set_num_cpus.

pub fn set_num_cpus(&self, count: usize)

Sets the value that BackgroundExecutor::num_cpus returns, in tests.

Panics

Panics if this executor isn’t a test executor.

pub fn is_main_thread(&self) -> bool

Returns whether the current thread is the main thread.

pub fn is_test(&self) -> bool

Whether this executor runs on the deterministic test scheduler.

Available in every build. Use it, rather than cfg(feature = "test-support"), for behavior that must differ under tests, so that compiling test-support into an application doesn’t change it.

Trait Implementations

impl Clone for BackgroundExecutor

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.