Struct AsyncApp 

pub struct AsyncApp { /* private fields */ }

A handle to the app that you can hold across .await points.

App can’t be borrowed across an .await, because the rest of the application needs it while your future waits. AsyncApp is the alternative: you get one as the argument of a future started with App::spawn, or from App::to_async. Each method borrows the app for the length of one call, runs a complete update, and releases the borrow. Entity methods are on the AppContext trait, which AsyncApp implements, so helpers written against that trait work here too.

AsyncApp holds a weak reference to the app, so it doesn’t keep the app alive. Most methods panic if the app has been released. The AppContext methods that return a Result or Option, such as update_window and with_window, report it as an error or None instead. Keep an AsyncApp only inside the futures that use it. One stored somewhere else can outlive the app.

See contexts for how async contexts fit with the other contexts.

Examples

use gpui::{AppContext, TestApp};

let mut app = TestApp::new();
let count = app.update(|cx| cx.new(|_| 0_usize));

let task = app.to_async().spawn({
    let count = count.clone();
    async move |cx| {
        cx.update(|cx| {
            count.update(cx, |count, cx| {
                *count += 1;
                cx.notify();
            })
        });
    }
});
task.detach();

app.run_until_parked();
app.read(|cx| assert_eq!(*count.read(cx), 1));

Implementations

impl AsyncApp

pub fn refresh(&self)

Schedules a redraw of every window.

The windows draw on the next frame. This doesn’t draw anything itself.

pub fn background_executor(&self) -> &BackgroundExecutor

Returns the BackgroundExecutor, for running work on other threads.

pub fn is_test(&self) -> bool

Whether this app runs on the deterministic test scheduler. See BackgroundExecutor::is_test.

pub fn foreground_executor(&self) -> &ForegroundExecutor

Returns the ForegroundExecutor, for running futures on the main thread.

pub fn update<R>(&self, f: impl FnOnce(&mut App) -> R) -> R

Runs f with the app and returns its result.

Effects queued by f, such as notifications, are flushed before this returns.

Panics

Panics if the app has been released, or if it is already borrowed, such as when called from inside another update.

pub fn subscribe<T, Event>( &mut self, entity: &Entity<T>, on_event: impl FnMut(Entity<T>, &Event, &mut App) + 'static, ) -> Subscription

where T: 'static + EventEmitter<Event>, Event: 'static,

Calls on_event each time entity emits an Event.

The callback receives the emitting entity, the event and the app. The subscription stays active while you hold it. Dropping it unsubscribes, and Subscription::detach keeps the subscription for as long as the entity lives. Inside an entity’s own context, Context::subscribe is the usual choice.

pub fn open_window<V>( &self, options: WindowOptions, build_root_view: impl FnOnce(&mut Window, &mut App) -> Entity<V>, ) -> Result<WindowHandle<V>>

where V: 'static + Render,

Opens a window with options and returns a handle to it.

build_root_view creates the window’s root view. The method returns an error if the app is quitting.

Panics

Panics if the app has been released, or if it is already borrowed.

pub fn spawn<AsyncFn, R>(&self, f: AsyncFn) -> Task<R>

where AsyncFn: AsyncFnOnce(&mut AsyncApp) -> R + 'static, R: 'static,

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

f receives an &mut AsyncApp. Dropping the returned Task cancels the future, so store it, await it or call Task::detach.

pub fn has_global<G: Global>(&self) -> bool

Returns whether a global of type G has been set.

pub fn read_global<G: Global, R>(&self, read: impl FnOnce(&G, &App) -> R) -> R

Calls read with the global of type G and the app, and returns its result.

Use AsyncApp::try_read_global if the global may not be set.

Panics

Panics if no global of type G has been set, or if the app has been released.

pub fn try_read_global<G: Global, R>( &self, read: impl FnOnce(&G, &App) -> R, ) -> Option<R>

Like AsyncApp::read_global, but returns None instead of panicking when no global of type G is set, or when the app is quitting.

pub fn read_default_global<G: Global + Default, R>( &self, read: impl FnOnce(&G, &App) -> R, ) -> R

Like AsyncApp::read_global, but first sets a G::default() if no global of type G has been set.

pub fn update_global<G: Global, R>( &self, update: impl FnOnce(&mut G, &mut App) -> R, ) -> R

Updates the global of type G with update, and returns its result.

While update runs, the global is taken out of the app. Reading it through the app from inside update panics, so change the global through the &mut G that update receives.

Panics

Panics if no global of type G has been set, or if the app has been released.

pub fn on_drop<T: 'static, Callback: FnOnce(&mut T, &mut Context<'_, T>) + 'static>( &self, entity: &WeakEntity<T>, f: Callback, ) -> Deferred<impl FnOnce() + use<T, Callback>>

Returns a guard that calls f with entity when the guard is dropped.

f doesn’t run if the entity has been released by then. Hold the guard in a variable. A guard that is dropped at once runs f immediately.

Examples

use gpui::{AppContext, TestApp};

let mut app = TestApp::new();
let log = app.update(|cx| cx.new(|_| Vec::<&'static str>::new()));
let guard = app.update(|cx| {
    cx.to_async().on_drop(&log.downgrade(), |log, cx| {
        log.push("finished");
        cx.notify();
    })
});
drop(guard);
app.read(|cx| assert_eq!(*log.read(cx), vec!["finished"]));

Trait Implementations

impl AppContext for AsyncApp

fn new<T: 'static>( &mut self, build_entity: impl FnOnce(&mut Context<'_, T>) -> T, ) -> Entity<T>

Creates an entity from build_entity, and returns a handle to it.

fn reserve_entity<T: 'static>(&mut self) -> Reservation<T>

Reserves an entity slot, and returns a Reservation for it.

fn insert_entity<T: 'static>( &mut self, reservation: Reservation<T>, build_entity: impl FnOnce(&mut Context<'_, T>) -> T, ) -> Entity<T>

Creates the entity for a Reservation from AppContext::reserve_entity.

fn update_entity<T: 'static, R>( &mut self, handle: &Entity<T>, update: impl FnOnce(&mut T, &mut Context<'_, T>) -> R, ) -> R

Runs update with the entity and a Context for it, and returns the result.

fn as_mut<'a, T>(&'a mut self, _handle: &Entity<T>) -> GpuiBorrow<'a, T>

where T: 'static,

Borrows the entity mutably, without a closure.

fn read_entity<T, R>( &self, handle: &Entity<T>, callback: impl FnOnce(&T, &App) -> R, ) -> R

where T: 'static,

Reads the entity with a shared borrow, and returns the result of read.

fn notify(&mut self, entity_id: EntityId)

Tells GPUI that the entity with entity_id changed. Its observers run and windows that show it redraw.

fn emit<EntityType, EventType>( &mut self, entity: &Entity<EntityType>, event: EventType, )

where EntityType: EventEmitter<EventType>, EventType: 'static,

Emits event from entity.

fn update_window<T, F>(&mut self, window: AnyWindowHandle, f: F) -> Result<T>

where F: FnOnce(AnyView, &mut Window, &mut App) -> T,

Runs f with the window’s root view, the window and the app, and returns the result.

fn with_window<R>( &mut self, entity_id: EntityId, f: impl FnOnce(&mut Window, &mut App) -> R, ) -> Option<R>

Runs f with the window that most recently rendered the entity entity_id, and returns the result.

fn read_window<T, R>( &self, window: &WindowHandle<T>, read: impl FnOnce(Entity<T>, &App) -> R, ) -> Result<R>

where T: 'static,

Reads the root view of window with the app, and returns the result.

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

where R: Send + 'static,

Runs future on the background executor and returns a task for its result.

fn read_global<G, R>(&self, callback: impl FnOnce(&G, &App) -> R) -> R

where G: Global,

Calls callback with the global of type G and the app, and returns the result.

fn insert_global_entity<T: 'static>(&mut self, entity: Entity<T>)

Keeps entity alive without a handle to it.

fn remove_global_entity<T: 'static>(&mut self, entity: &Entity<T>)

Stops keeping entity alive. It’s dropped once no other handle refers to it.

fn global_entities<T: 'static>(&self) -> impl Iterator<Item = Entity<T>>

Returns the entities stored with AppContext::insert_global_entity whose type is T.

impl Clone for AsyncApp

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.