Hosting and External Updates
Keep views on the UI thread while asynchronous services submit bounded model changes through AppHandle.
AppHost connects an application's UI lifecycle to Hera's transport and retained outcomes. Its factory runs once on a dedicated UI thread, where it constructs the views, runtime, and models that will remain owned by that thread. This allows the model to use Rc without requiring those values to cross thread boundaries.
Host Configuration
Construct the host with AppHost::new(factory) and configure an initial surface name and logical proposal through .with_window(name, initial_size). Calling .run(socket_path).await begins the session: the host connects, negotiates a surface, and dispatches messages until shutdown or failure.
The host follows authoritative SurfaceChanged geometry after startup. A changed initial size is not a protocol request to override the shell's window policy.
Background Result Delivery
.with_updates() returns the host and a cloneable AppHandle. Its update method accepts a Send + 'static closure that the UI thread applies to the runtime and environment.
use hera_kit::{AppHost, EnvKey, text, view_fn};
struct Status;
impl EnvKey for Status {
type Value = String;
fn default() -> String { "Loading".into() }
}
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let (host, handle) = AppHost::new(|_, _| view_fn(|cx| {
Ok(text(cx.environment::<Status>()))
})).with_updates();
tokio::spawn(async move {
let result = "Ready".to_owned(); // Replace with a service result.
handle.update(move |rt, env| env.set::<Status>(rt, result)).await
});
host.run("/tmp/hera.sock").await?;
Ok(())
}The task moves a plain service result into the callback and updates the root environment on the UI thread. In an application service, observe the update result so host shutdown can be handled deliberately. Do not move UI-owned Rc values into a cross-thread closure.
Update Completion
Awaiting an update tells the caller that its mutation callback ran on the UI thread. The resulting scene may still be waiting for evaluation, retained acceptance, GPU submission, or presentation. Once the mutation has been admitted to the queue, dropping the waiting future does not undo it.
Keep I/O and long-running computation in the service task, then return their result through a short update callback. If that callback blocked the UI thread waiting for another update on its own handle, the queued work could never run. Keeping the callback focused on model mutation allows both transport and UI progression to continue.
Ordered Commit Outcomes
The host keeps one nonempty candidate pending until the server resolves it. Model updates can continue during that wait, but follow-up evaluation uses the latest model only after acceptance or rejection establishes the correct scene baseline.
The host also bounds its asynchronous waits for startup, writes, UI command delivery, and retained outcomes. An expired wait ends the transport session without replaying ambiguous work. These deadlines govern waiting rather than arbitrary user execution, so they cannot preempt a callback that is already running.
Read threading internals for queues and commit outcomes for publication semantics.
Source Reference
The following files in the Hera checkout define the behavior described on this page.
crates/kit/src/host/mod.rscrates/kit/src/host/updates.rscrates/kit/src/threading/mod.rs