Ownership and data flow in GPUI

Note: This blog post was originally written for an old version of GPUI. It has been updated to reflect the current GPUI APIs, as of 12/12/25.

One of the challenges we initially faced building Zed's user interface was Rust's strict ownership system. In Rust, every object has a single unique owner, which strongly encourages all data to be organized as a tree without cyclic references or shared ownership. Prior to building Zed, most of my experience writing GUI code was with web technology, where the JavaScript garbage collector means you don't really need to think about ownership. It's easy, for example, to attach a mouse event listener to a DOM node that captures a reference to this, and most of my intuition about building UI was based on this paradigm. In Rust, capturing self in an event listener is the opposite of straightforward.

So when we started on Zed in 2019, it was clear that we would need to rethink much of what we'd learned using the web and other frameworks. We needed a system that fit well with Rust, but we also needed dynamism to express a real-world graphical interface. For example, Zed's workspace can display modal dialogs of various types, and these dialogs need to be able to emit events to the workspace to indicate when they should be closed. We also needed to support updating subtrees asynchronously, such as in the project panel when the file system changes. There are of course many more examples, and we wanted to handle them all without forcing the use of exotic data structures to represent application state. As much as possible, we wanted to avoid macros and use plain Rust structs.

After initial attempts to use built-in types such as Rc went poorly, we began experimenting with an approach that persists to this day in Zed's custom-built UI framework, GPUI. In GPUI, every model or view in the application is actually owned by a single top-level object called the App. When you create a new model or view, which we refer to collectively as entities, you give the application ownership of the state to enable it to participate in a variety of app services and interact with other entities.

To illustrate, consider the trivial app below. We start the app by calling run with a callback, which is passed a reference to the App that owns all the state for the application. This App is our gateway to all application-level services, such as opening windows, presenting dialogs, etc. It also has a new method, which we call below to create an entity and give ownership of it to the application.

use gpui::{prelude::*, Application, App, Entity};
 
struct Counter {
    count: usize,
}
 
fn main() {
    Application::new().run(|cx: &mut App| {
        let counter: Entity<Counter> = cx.new(|_cx| Counter { count: 0 });
        // ...
    });
}

The call to new returns an entity handle, which carries a type parameter based on the type of object it references. By itself, this Entity<Counter> handle doesn't provide access to the entity's state. It's merely an inert identifier plus a compile-time type tag, and it maintains a reference count to the underlying Counter object that is owned by the app.

Much like an Rc from the Rust standard library, this reference count is incremented when the handle is cloned and decremented when it is dropped to enable shared ownership to the underlying entity, but unlike an Rc it only provides access to the entity's state when a reference to an App is available. The handle doesn't truly own the state, but it can be used to access the state from its true owner, the App. Let's continue our simple example and use the context to increment the counter. I'll strip away some of the setup code for brevity.

Application::new().run(|cx: &mut App| {
    let counter = cx.new(|_cx| Counter { count: 0 });
    // Call `update` to access the entity's state.
    counter.update(cx, |counter: &mut Counter, cx: &mut Context<Counter>| {
        counter.count += 1;
    });
});

To update the counter, we call update on the handle, passing the context reference and a callback. The callback is yielded a mutable reference to the counter, which we can use to manipulate state.

The callback is also provided a second Context<Counter> reference. This reference is similar to the App reference provided to the run callback. A Context is actually a wrapper around the App, but it includes some additional data that ties it to a particular entity, in this case our counter.

In addition to the application-level services provided by App, a Context provides access to entity-level services. For example, we can use it to inform observers of this entity that its state has changed. Let's add that to our example, by calling cx.notify().

Application::new().run(|cx: &mut App| {
    let counter = cx.new(|_cx| Counter { count: 0 });
    counter.update(cx, |counter, cx| {
        counter.count += 1;
        cx.notify(); // Notify observers
    });
});

Next lets see how we can observe these notifications. Before we update the counter, we'll construct a second counter that observes it. Whenever the first counter changes, we'll assign double its count to the second counter. Note how we call observe on the Context belonging to our second counter to arrange for it to be notified whenever the first counter notifies. The call to observe returns a Subscription, which we detach to preserve this behavior for as long as both counters exist. We could also store this subscription and drop it at a time of our choosing to cancel this behavior.

The observe callback is passed a mutable reference to the observer and a handle to the observed counter, whose state we access with the read method.

Application::new().run(|cx: &mut App| {
    let counter: Entity<Counter> = cx.new(|_cx| Counter { count: 0 });
    let observer = cx.new(|cx: &mut Context<Counter>| {
        cx.observe(&counter, |observer, observed, cx| {
            observer.count = observed.read(cx).count * 2;
        })
        .detach();
 
        Counter {
            count: 0,
        }
    });
 
    counter.update(cx, |counter, cx| {
        counter.count += 1;
        cx.notify();
    });
 
    assert_eq!(observer.read(cx).count, 2);
});

After updating the first counter, you see that the observing counters state is maintained according to our subscription.

In addition to observe and notify, which indicate that an entity's state has changed, GPUI also offers subscribe and emit, which enables entities to emit typed events. To opt into this system, the emitting object must implement the EventEmitter trait.

Let's introduce a new event type called CounterChangeEvent, then indicate that Counter can emit this type of event.

struct CounterChangeEvent {
    increment: usize,
}
 
impl EventEmitter<CounterChangeEvent> for Counter {}

Next, we'll update our example, replacing the observation with a subscription. Whenever we increment the counter, we'll emit a Change event to indicate by how much it's increasing.

Application::new().run(|cx: &mut App| {
    let counter: Entity<Counter> = cx.new(|_cx| Counter { count: 0 });
    let subscriber = cx.new(|cx: &mut Context<Counter>| {
        cx.subscribe(&counter, |subscriber, _emitter, event, _cx| {
            subscriber.count += event.increment * 2;
        })
        .detach();
 
        Counter {
            count: counter.read(cx).count * 2,
        }
    });
 
    counter.update(cx, |counter, cx| {
        counter.count += 2;
        cx.emit(CounterChangeEvent { increment: 2 });
        cx.notify();
    });
 
    assert_eq!(subscriber.read(cx).count, 4);
});

Now let's dig a bit into GPUI's internals to explore how observation and subscriptions are implemented.

Before diving into the details of GPUI's event handling, I'd like to recount an instructive experience from my past work on the Atom editor, where I had implemented a custom event system in JavaScript. At that time, I designed what seemed like a straightforward event emitter, where event listeners were kept in an array and each listener was called sequentially when an event was emitted.

This simplicity, however, led to a subtle bug that went unnoticed until the code was widely used in production. The problem manifested when one listener function emitted an event to the same emitter it was subscribed to. This inadvertently triggered reentrancy, where the emitting function was called again before it had completed its execution. This recursive-like behavior contradicted our expectation of linear function execution and got us into an unexpected state. Even though JavaScript's garbage collector enforces memory safety, the language's relaxed ownership model made it easy for me to write this bug.

Rust's constraints make this naive approach to rather more difficult. We're strongly encouraged down a different path, which prevents the kind of reetrancy I described above. In GPUI, when you call emit or notify, no listeners are invoked. Instead, we push data to a queue of effects. At the end of each update we flush these effects, popping from the front of the queue until it becomes empty and then returning control to the event loop. Any effect handler can itself push more effects, but the system eventually quiesces. This gives us run-to-completion semantics without reentrancy bugs and plays nicely with Rust.

Here's the core of this approach from app.rs. I'll explain below.

impl App {
    pub(crate) fn update<R>(&mut self, update: impl FnOnce(&mut Self) -> R) -> R {
        self.pending_updates += 1;
        let result = update(self);
        if !self.flushing_effects && self.pending_updates == 1 {
            self.flushing_effects = true;
            self.flush_effects();
            self.flushing_effects = false;
        }
        self.pending_updates -= 1;
        result
    }
 
    fn flush_effects(&mut self) {
        loop {
            self.release_dropped_entities();
            self.release_dropped_focus_handles();
 
            if let Some(effect) = self.pending_effects.pop_front() {
                match effect {
                    Effect::Notify { emitter } => {
                        self.apply_notify_effect(emitter);
                    }
 
                    Effect::Emit {
                        emitter,
                        event_type,
                        event,
                    } => self.apply_emit_effect(emitter, event_type, event),
 
                    // A few more effects, elided for clarity
                }
            } else {
                for window in self.windows.values() {
                    if let Some(window) = window.as_ref() {
                        if window.dirty {
                            window.platform_window.invalidate();
                        }
                    }
                }
 
                break;
            }
        }
    }
 
    // Lots more methods...
}

The App::update method does some book-keeping to allow itself to be called reentrantly. Before exiting the topmost call, it calls flush_effects. The flush_effects method is a loop. On every turn, we release dropped entities and focus handles, which drops ownership of resources whose reference count has reached 0. We then remove the next effect from the queue and apply it. If no next effect exists, we iterate over the windows, and for any that are dirty, we invalidate the platform window so it is scheduled to draw on the next frame. We then break the loop.

Next let's use App::update to implement update_entity. I'll scaffold it below so we can discuss its signature before proceeding with implementation.

impl App {
    fn update_entity<T: 'static, R>(
        &mut self,
        handle: &Entity<T>,
        update: impl FnOnce(&mut T, &mut Context<T>) -> R,
    ) -> R {
        todo!()
    }
}

The method takes a callback that expects two mutable references, one to the state of the entity referenced by the given handle, and a second to a Context, which as I mentioned above, actually just wraps App. Since the App owns the entity, this initially seems to require multiple mutable borrows to the same data, which Rust prohibits.

Our workaround is to temporarily "lease" the entity state from the App, removing it from the context and moving it to the stack. After we invoke the callback, we end the lease, restoring ownership to the context.

impl App {
    fn update_entity<T: 'static, R>(
        &mut self,
        handle: &Entity<T>,
        update: impl FnOnce(&mut T, &mut Context<T>) -> R,
    ) -> R {
        self.update(|cx| {
            let mut entity = cx.entities.lease(handle);
            let result = update(&mut entity, &mut Context::new_context(cx, handle.downgrade()));
            cx.entities.end_lease(entity);
            result
        })
    }
}

This does spell trouble if you ever attempt to update an entity reentrantly, but in practice we've found it quite manageable to avoid this, and it's pretty been quick and easy to detect when we've made errors.

Now that I've covered the basics of how state is managed in GPUI, the next thing to cover is how we present that state on screen with views. But that will have to wait for our next installment. Until then, have a look around our source code and join us live in Zed today for our first Fireside Hack. It happens to be my birthday, and I can't think of a better way to spend it than hanging out in Zed with you.

Check out similar blogs from the Zed team.