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 allocate( cx: &impl Actor, alloc: Box<dyn Alloc + Send + Sync>, name: &str, bootstrap_params: Option<BootstrapCommand>, ) -> Result<Self>

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::v1::host_mesh::mesh_agent::HostMeshAgent 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(name: impl Into<Name>, 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 shutdown(&self, cx: &impl Actor) -> Result<()>

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

For each host, this sends ShutdownHost to its HostMeshAgent. 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( &self, cx: &impl Actor, name: &str, per_host: Extent, ) -> Result<ProcMesh>

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.

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.