Struct HostMesh 

pub struct HostMesh { /* private fields */ }

An owned mesh of hosts.

Lifecycle

HostMesh owns host lifecycles. Callers must invoke HostMesh::shutdown for deterministic teardown. The Drop impl performs best-effort cleanup only (spawned via Tokio if available); it is a safety net, not a substitute for orderly shutdown.

In tests and production, prefer explicit shutdown to guarantee that host agents drop their BootstrapProcManagers and that all child procs are reaped.

Implementations

impl HostMesh

pub async fn local() -> Result<HostMesh>

Bring up a local single-host mesh and, in the launcher process, return a HostMesh handle for it.

There are two execution modes:

• bootstrap-child mode: if Bootstrap::get_from_env() says this process was launched as a bootstrap child, we call boot.bootstrap().await, which hands control to the bootstrap logic for this process (as defined by the BootstrapCommand the parent used to spawn it). if that call returns, we log the error and terminate. this branch does not produce a HostMesh.

• launcher mode: otherwise, we are the process that is setting up the mesh. we create a Host, spawn a HostAgent in it, and build a single-host HostMesh around that. that HostMesh is returned to the caller.

This API is intended for tests, examples, and local bring-up, not production.

TODO: fix up ownership

pub async fn local_with_bootstrap( bootstrap_cmd: BootstrapCommand, ) -> Result<HostMesh>

Same as [local], but the caller supplies the BootstrapCommand instead of deriving it from the current process.

The provided bootstrap_cmd is used when spawning bootstrap children and determines the behavior of boot.bootstrap().await in those children.

pub async fn local_in_process() -> Result<HostMesh>

Create a local in-process host mesh where all procs run in the current OS process.

Unlike [local] which spawns child processes for each proc, this method uses LocalProcManager to run everything in-process. This makes all actors visible in the admin tree (useful for debugging with the TUI).

This API is intended for tests, examples, and debugging.

pub async fn process( extent: Extent, command: BootstrapCommand, ) -> Result<HostMesh>

Create a new process-based host mesh. Each host is represented by a local process, which manages its set of procs. This is not a true host mesh the sense that each host is not independent. The intent of process is for testing, examples, and experimentation.

The bootstrap command is used to bootstrap both hosts and processes, thus it should be a command that reaches crate::bootstrap_or_die. process is itself a valid bootstrap entry point; thus using BootstrapCommand::current works correctly as long as process is called early in the lifecycle of the process and reached unconditionally.

TODO: thread through ownership

pub async fn allocate<C: Actor>( cx: &C, alloc: Box<dyn Alloc + Send + Sync>, name: &str, bootstrap_params: Option<BootstrapCommand>, ) -> Result<Self>

where C::A: Handler<MeshFailure>,

Allocate a host mesh from an Alloc. This creates a HostMesh with the same extent as the provided alloc. Allocs generate procs, and thus we define and run a Host for each proc allocated by it.

Allocation strategy

Because HostMeshes use direct-addressed procs, and must fully control the procs they are managing, HostMesh::allocate uses a trampoline actor to launch the host, which in turn runs a crate::host_mesh::host_agent::HostAgent actor to manage the host itself. The host (and thus all of its procs) are exposed directly through a separate listening channel, established by the host.

                       ┌ ─ ─┌────────────────────┐
                            │allocated Proc:     │
                       │    │ ┌─────────────────┐│
                            │ │TrampolineActor  ││
                       │    │ │ ┌──────────────┐││
                            │ │ │Host          │││
              ┌────┬ ─ ┘    │ │ │ ┌──────────┐ │││
           ┌─▶│Proc│        │ │ │ │HostAgent │ │││
           │  └────┴ ─ ┐    │ │ │ └──────────┘ │││
           │  ┌────┐        │ │ │             ██████
┌────────┐ ├─▶│Proc│   │    │ │ └──────────────┘││ ▲
│ Client │─┤  └────┘        │ └─────────────────┘│ listening channel
└────────┘ │  ┌────┐   └ ─ ─└────────────────────┘
           ├─▶│Proc│
           │  └────┘
           │  ┌────┐
           └─▶│Proc│
              └────┘
                ▲

         `Alloc`-provided
               procs

Lifecycle

The returned HostMesh owns the underlying hosts. Call shutdown to deterministically tear them down. If you skip shutdown, Drop will attempt best-effort cleanup only. Do not rely on Drop for correctness.

pub fn take(mesh: HostMeshRef) -> Self

Take ownership of an existing host mesh reference.

Consumes the HostMeshRef, captures its region/hosts, and returns an owned HostMesh that assumes lifecycle responsibility for those hosts (i.e., will shut them down on Drop).

pub async fn attach( cx: &impl Actor, name: Name, addresses: Vec<ChannelAddr>, ) -> Result<Self>

Attach to pre-existing workers and push client config.

This is the “simple bootstrap” attach protocol:

1. Wraps the provided addresses into a HostMeshRef.
2. Snapshots propagatable_attrs() from the client’s global config.
3. Pushes the config to each host agent as Source::ClientOverride, with a barrier to confirm installation.
4. Returns the owned HostMesh.

After this returns, host agents have the client’s config and any subsequent operations on the host’s system proc (e.g. SpawnMeshAdmin) will see it.

pub async fn shutdown(&mut self, cx: &impl Actor) -> Result<()>

Request a clean shutdown of all hosts owned by this HostMesh.

For each host, this sends ShutdownHost to its HostAgent. The agent takes and drops its Host (via Option::take()), which in turn drops the embedded BootstrapProcManager. On drop, the manager walks its PID table and sends SIGKILL to any procs it spawned—tying proc lifetimes to their hosts and preventing leaks.

Methods from Deref<Target = HostMeshRef>

pub async fn spawn<C: Actor>( &self, cx: &C, name: &str, per_host: Extent, ) -> Result<ProcMesh>

where C::A: Handler<MeshFailure>,

Spawn a ProcMesh onto this host mesh. The per_host extent specifies the shape of the procs to spawn on each host.

Currently, spawn issues direct calls to each host agent. This will be fixed by maintaining a comm actor on the host service procs themselves.

pub fn name(&self) -> &Name

The name of the referenced host mesh.

pub fn hosts(&self) -> &[HostRef]

The host references (channel addresses) in rank order.

pub async fn spawn_admin( &self, cx: &impl Actor, admin_addr: Option<SocketAddr>, ) -> Result<String>

Spawn a [MeshAdminAgent] on the head host’s system proc and return its HTTP address.

Sends a SpawnMeshAdmin message to ranks[0]’s HostAgent, which spawns the admin agent on that host’s system proc. When admin_addr is Some, the HTTP server binds to that address; otherwise it reads MESH_ADMIN_ADDR from config.

Trait Implementations

impl Deref for HostMesh

type Target = HostMeshRef

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl Drop for HostMesh

fn drop(&mut self)

Best-effort cleanup for owned host meshes on drop.

When a HostMesh is dropped, it attempts to shut down all hosts it owns:

• If a Tokio runtime is available, we spawn an ephemeral Proc + Instance and send ShutdownHost messages to each host. This ensures that the embedded BootstrapProcManagers are dropped, and all child procs they spawned are killed.
• If no runtime is available, we cannot perform async cleanup here; in that case we log a warning and rely on kernel-level PDEATHSIG or the individual BootstrapProcManager’s Drop as the final safeguard.

This path is last resort: callers should prefer explicit HostMesh::shutdown to guarantee orderly teardown. Drop only provides opportunistic cleanup to prevent process leaks if shutdown is skipped.