Module host 

Host lifecycle management for procs running on one machine.

A Host owns one Gateway and one ProcManager. The manager makes procs real, either by spawning them in-process for tests or by launching separate OS processes. The gateway owns connectivity: it serves the backend and frontend endpoints, multiplexes inbound traffic to in-process procs, and routes spawned child proc gateways through peer routes.

Use Host::new or Host::new_with_gateway to construct a host, start its backend and frontend accept loops, then Host::spawn to create child procs. Spawned children are returned as ProcAddr values whose location is advertised through this host’s gateway.

Gateway topology

A host gateway exposes a frontend endpoint * and serves a backend endpoint # for child proc gateways. Each spawned child has its own gateway endpoint (#1, #2, …), uses # as its forwarder, and is advertised as Via(child_uid, host_location). The host_location is the host gateway’s advertised location: the newest active frontend serve or serve_via session.

The host gateway keeps one peer route per child uid. When it receives a message for Via(child_uid, host_location), it peels the child hop and forwards the envelope to the child’s gateway. In-process service and local procs are delivered through the gateway’s local proc table.

inbound to host_location
(*, or Via(...) when attached)
         |
         v
  +---------------+     peer child_uid_1 -> #1     +----------------------+
  | Host Gateway  |------------------------------->| child gateway/proc 1 |
  | local procs:  |                                | addr #1              |
  | service/local |<-------------------------------| forwarder -> #       |
  +---------------+          host backend #         +----------------------+
         |
         | peer child_uid_2 -> #2
         v
  +----------------------+
  | child gateway/proc 2 |
  | addr #2              |
  | forwarder -> #       |
  +----------------------+

The built-in service and local procs are created during construction and run in-process on the host gateway. The local proc starts with no actors; a ProcAgent and root client actor are added lazily when HostMeshAgent::handle(GetLocalProc) first asks for it.

Modules

testing

Testing support for hosts. This is linked outside of cfg(test) as it is needed by an external binary.

Structs

Host

Lifecycle manager for the procs on one machine.

LocalHandle

A lightweight ProcHandle for procs managed in-process via LocalProcManager.

LocalProcManager

A ProcManager that spawns in-process procs (test-only).

ProcessHandle

A ProcHandle implementation for procs managed as separate OS processes via ProcessProcManager.

ProcessProcManager

A ProcManager that manages each proc as a separate OS process (test-only toy).

ReadyProc

Capability proving a proc is ready.

TerminateSummary

Summary of results from a bulk termination attempt.

Enums

HostError

The type of error produced by host operations.

LocalProcStatus

Lifecycle status for procs managed by LocalProcManager.

ReadyError

Error returned by ProcHandle::ready.

ReadyProcError

Error returned by [ready_proc].

TerminateError

Error returned by ProcHandle::terminate and ProcHandle::kill.

WaitError

Error returned by ProcHandle::wait.

Constants

LOCAL_PROC_NAME

Name of the local client proc on a host.

SERVICE_PROC_NAME

Name of the system service proc on a host.

Traits

BulkTerminate

Trait for managers that can terminate many child units in bulk.

ProcHandle

Minimal uniform surface for a spawned-proc handle returned by a ProcManager. Each manager can return its own concrete handle, as long as it exposes these. A proc is the Hyperactor runtime

ProcManager

A trait describing a manager of procs, responsible for bootstrapping procs on a host, and managing their lifetimes. The manager spawns an Agent-typed actor on each proc, responsible for managing the proc.

SingleTerminate

Trait for terminating a single proc.

Functions

spawn_proc

Spawn a proc at proc_id with an A-typed agent actor, forwarding messages to the provided backend_addr, and returning the proc’s address and agent actor on the provided callback_addr.

Type Aliases

ManagerAgent

Type alias for the agent actor managed by a given ProcManager.