From dbbeac79e5d54db224eb11ece8600f11302a643b Mon Sep 17 00:00:00 2001 From: kirillDevPro <113171057+kirillDevPro@users.noreply.github.com> Date: Thu, 24 Sep 2026 07:14:54 +0200 Subject: [PATCH] docs(gpui): correct async and test context docs contexts.md said every async entity call is fallible and that TestAppContext panics when the app or window is missing. Entity::update on AsyncApp panics if the app is gone. Window updates return Result. TestAppContext owns the app, and its update_window returns Result. --- crates/moon-gpui/docs/contexts.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/crates/moon-gpui/docs/contexts.md b/crates/moon-gpui/docs/contexts.md index 9295c77..71a4fb0 100644 --- a/crates/moon-gpui/docs/contexts.md +++ b/crates/moon-gpui/docs/contexts.md @@ -14,11 +14,13 @@ A context provided when interacting with an `Entity`, with additional methods ## `AsyncApp` and `AsyncWindowContext` -Whereas the above contexts are always passed to your code as references, you can call `to_async` on the reference to create an async context, which has a static lifetime and can be held across `await` points in async code. When you interact with entities with an async context, the calls become fallible, because the context may outlive the window or even the app itself. +`App::to_async` and `TestAppContext::to_async` return an `AsyncApp`. `Context` dereferences to `App`, so `to_async` on a context reference is `App::to_async` and returns an `AsyncApp` as well. `Window::to_async` takes `&App` and returns an `AsyncWindowContext`. `Context::spawn` passes the task a `WeakEntity` and an `&mut AsyncApp`, and `Context::spawn_in` passes an `&mut AsyncWindowContext`. Both async contexts have a static lifetime and can be held across `await` points. + +`AsyncApp` holds a weak reference to the app. `Entity::update` on an `AsyncApp` panics if the app has already been dropped, and that call does not return `Result`. `AsyncApp::update_window` and `AsyncWindowContext::update` return `Result` when the app has been dropped, the app is quitting, or the window is gone. `WeakEntity::update` returns `Result` when the entity was released, on every context, not only an async one. ## `TestAppContext` -These are similar to the async contexts above, but they panic if you attempt to access a non-existent app or window, and they also contain other features specific to tests. +A `#[gpui::test]` that takes `&mut TestAppContext` receives one. The context owns the app through `Rc`, so a dropped app is not one of its failure modes. `TestAppContext::update_window` returns `Result` when the window is gone. `VisualTestContext::update` unwraps that result and panics. The test context also exposes input and window helpers such as `simulate_input` and `simulate_window_resize`. --- @@ -26,7 +28,7 @@ These are similar to the async contexts above, but they panic if you attempt to ## `Window` -Provides access to the state of an application window. This type has a root view (an `Entity` implementing `Render`) which it can read/update, but since it is not a context, you must pass a `&mut App` (or a context which dereferences to it) to do so, along with other functions interacting with global state. You can obtain a `Window` from an `WindowHandle` by calling `WindowHandle::update`. +`Window` is the state of one window, including its root view (an `Entity` that implements `Render`). It is not a context. `WindowHandle::update` takes an `AppContext` — `&mut App`, or a `Context`, which dereferences to `App` — and a closure. The closure receives `&mut V`, `&mut Window`, and `&mut Context`. The call returns `Result`, because the window may already be closed. ## `Entity`