0010 - Typed events, delivered on the main thread
Status: Accepted (2026-11-17)
Context
Phase 1 needs app-wide events: a command finishes an import, a background task makes progress, a
view wants to announce something to other views. The project forbids stringly-typed dispatch
(ADR 0002) and requires UI mutation on the GPUI main thread (ADR 0004). Commands run on Auro's
tokio runtime, so a background producer cannot touch App, entities or windows directly.
Options considered:
- A string topic bus (Tauri's
emit/listenshape). Rejected: a renamed event becomes a silent runtime no-op, which is the failure mode Auro exists to remove. - GPUI's per-entity
EventEmitteronly. Useful for parent/child wiring, but a command has no entity and app-wide delivery would still need a fan-out mechanism. - A typed event queue keyed by
TypeId, with a main-thread pump. Chosen. - Synchronous callbacks from the worker thread. Rejected: they would let background code mutate UI state and violate the threading contract.
Decision
auro-core owns a renderer-agnostic channel. Any E: Send + 'static can be emitted.
EventSenderis cloneable,Send + Sync, and auto-managed in the state store, so a command can takeState<EventSender>and callsender.emit(event). It boxes the event with itsTypeIdand queues it on an unboundedtokio::sync::mpscchannel.emitreturnsfalsewhen the app is gone.- The facade installs an
EventBusglobal and a foreground pump. The pump awaits the receiver and dispatches each event on the main thread throughAsyncApp::update. App::on_event::<E>(|event, cx| ...)registers a handler before the app runs. Handlers are keyed byTypeId, run in registration order, and receive&mut Appso they can update entities and callcx.notify(). A panic propagates.emit(event, cx)is the main-thread path and dispatches synchronously. Background producers must useEventSender.- An event with no subscriber is dropped; there is no error and no fallback to a string topic.
- Handler lists are cloned before dispatch, so a handler can emit (or cause a close/lifecycle
event) without tripping a
RefCellborrow.
Ordering is FIFO per producer through the queue. A main-thread emit can interleave with queued
events; there is no total order across producers. The queue is unbounded and has no backpressure in
this slice.
Consequences
Easier
- Commands and views share one typed event path with no string names.
- Events reach the UI on the correct thread without every app inventing its own channel.
- The event type is a Rust type: renames and payload changes are compile errors.
Harder
- A flooding producer can grow memory because the channel is unbounded; a bounded/backpressure policy is deferred.
- Subscriptions are builder-time only; dynamic subscribe/unsubscribe needs a subscription handle and a lifetime story.
- Cross-producer ordering is not guaranteed; apps that need it must sequence their own work.
- Events are not persisted; a late subscriber misses earlier events.
Forbidden
- String event names, untyped payloads or worker-thread UI mutation.
- Treating "no subscriber" as an error; a dropped event is the documented behaviour.
Revisit when
- A real app needs backpressure, event coalescing or ordering guarantees.
- Dynamic subscriptions become common enough to justify a handle API.
- Events cross the process/plugin boundary (Phase 3), where serialization and schema matter.