Struct ForegroundExecutor 

pub struct ForegroundExecutor { /* private fields */ }

Runs futures on the main thread, interleaved with event handling and drawing.

Get one from App::foreground_executor or crate::AsyncApp::foreground_executor. Futures need only be 'static, so they can hold entity handles. Each poll runs until the future returns Pending or Ready; an await can complete immediately. Keep CPU-heavy work out of a foreground poll and move it to a BackgroundExecutor. See executors.

Implementations

impl ForegroundExecutor

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

Creates an executor that runs futures on the main thread through dispatcher.

Platform code creates the executor. Apps get one from App::foreground_executor or crate::AsyncApp::foreground_executor.

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

where R: 'static,

Runs future on the main thread, and returns a task for its result.

The future needn’t be Send, so it can hold entity handles and other state that lives on the main thread. Each poll runs until the future returns Pending or Ready; an await can complete immediately. Keep long computations out of a poll and use BackgroundExecutor::spawn for them. Dropping the task cancels the future, but cannot interrupt synchronous code already running on this thread.

Examples

use gpui::TestApp;

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

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

where R: 'static,

Like ForegroundExecutor::spawn. The priority is ignored: foreground futures run in the order they were spawned.

pub fn spawn_when_idle<R>( &self, timeout: Option<Duration>, future: impl Future<Output = R> + 'static, ) -> Task<R>

where R: 'static,

Runs future on the main thread when the platform is idle.

Use this for low-priority UI work that can wait. timeout sets how long the future may wait. None lets it wait as long as the platform stays busy. With a timeout, a poll that is still waiting after that long runs as ordinary main-thread work. On platforms without idle scheduling the future runs at low priority, and timeout is ignored.

Each poll uses part of one idle slice. Long synchronous stretches should check ForegroundExecutor::idle_time_remaining and yield when it runs low.

pub fn idle_time_remaining(&self) -> Option<Duration>

Returns how much of the current idle slice is left.

Call it from a future that was spawned with ForegroundExecutor::spawn_when_idle. Returns None on platforms that don’t meter idle time, and when the call isn’t inside an idle slice. In that case, fall back to a budget of your own.

pub fn block_test<R>(&self, future: impl Future<Output = R>) -> R

Runs future on the main thread until it completes, and returns its output. Only available in tests.

If the future is waiting and no other test work can run, the simulated clock moves to the next timer.

Panics

Panics if future is waiting, no timer is pending, and parking isn’t allowed.

pub fn block_on<R>(&self, future: impl Future<Output = R>) -> R

Blocks the current thread until future completes, and returns its output.

Prefer ForegroundExecutor::block_with_timeout, which gives up instead of waiting indefinitely.

pub fn block_with_timeout<R, Fut: Future<Output = R>>( &self, duration: Duration, future: Fut, ) -> Result<R, impl Future<Output = R> + use<R, Fut>>

Blocks the current thread until future completes or duration passes.

Returns Ok with the output if the future finished. Otherwise returns Err with the unfinished future, which you can poll later.

Examples

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

let app = TestApp::new();
let result = app
    .foreground_executor()
    .block_with_timeout(Duration::from_secs(1), async { 5 });
assert_eq!(result.ok(), Some(5));

Trait Implementations

impl Clone for ForegroundExecutor

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.