Documentation menu

Server and Lifecycle

Understand how the server coordinates clients, input, frame production, and orderly device teardown.

HeraServer coordinates the services that turn retained composition into a running display server. It handles asynchronous connections and renderer operations on behalf of the composer, keeping socket delivery and authentication policy outside the code that prepares scenes or executes GPU work.

Service Startup

Service startup begins in herad, which initializes tracing and translates deployment configuration into a Composer, a Renderer, and the configuration for HeraServer. It then calls run_until with a shutdown future. An application embedding the server can supply its own future, allowing it to use the same lifecycle without adopting the daemon's OS signal policy.

Startup establishes input and presentation readiness before the frame driver begins. Renderer construction can fail because the Vulkan device, DRM output, or requested presentation path is unavailable; those errors must be resolved before accepting a working display service.

Connection Ownership

After authenticating a connection and completing its hello exchange, the server tracks the surfaces and buffers owned by that client. It dispatches incoming requests to handlers for those resources, scene commits, and shell operations, so each feature can enforce its own lifecycle while sharing the connection's delivery machinery.

A connection has an independent writer so acknowledgments and release messages can progress while its reader waits for commit admission. When pending work reaches its budget, the server stops admitting more work from that connection instead of growing an unbounded retry queue.

Frame and Input Coordination

The frame driver connects composer preparation to renderer execution. For each planned presentation time, it requests a scene snapshot, submits that snapshot to the renderer, and reports the submission outcome. As identified presentation events arrive, it feeds their timestamps back into the scheduler to refine future plans.

The same service also delivers device input, using composer policy to resolve seat ownership and hit testing. To keep those decisions aligned with what the user sees, the renderer exposes the latest confirmed presented scene rather than only the newest submitted snapshot.

Shutdown Ordering

Shutdown follows the reverse ownership dependencies: supervised service work stops, the frame driver is joined, and renderer teardown can then retire GPU and display consumers before destroying their images, framebuffers, and devices. If teardown fails, the service remains terminal; the error does not make its partially retired renderer available for new commands.

See presentation and synchronization for resource retirement and protocol connection setup for the client-facing lifecycle.

Source Reference

The following files in the Hera checkout define the behavior described on this page.

  • apps/herad/src/main.rs
  • crates/server/src/runtime/mod.rs
  • crates/server/src/runtime/shutdown.rs
  • crates/server/src/client/dispatch.rs