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 HostMeshAgent 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 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( 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(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.

pub fn name(&self) -> &Name

The name of the referenced host mesh.

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.