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.

In tests and production, prefer explicit shutdown to guarantee that host agents drop their BootstrapProcManagers and that all child procs are reaped. You can use shutdown_guard to get a wrapper which will try to do a best-effort shutdown on Drop.

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.

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

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

Uses a two-phase approach:

1. Terminate children on every host concurrently. Service infrastructure (host agent, comm proc, networking) stays alive so that forwarder flushes can still reach remote hosts.
2. Shut down hosts concurrently. No user procs remain, so this is fast and cannot deadlock on cross-host flush timeouts.

pub fn shutdown_guard(self) -> HostMeshShutdownGuard

Consumes and wraps this HostMesh with a HostMeshShutdownGuard, which will ensure shutdown is run on Drop.

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

Stop all hosts owned by this HostMesh, draining user procs but keeping worker processes and their sockets alive for reconnection.

After stop, the same worker addresses can be passed to HostMesh::attach to create a new mesh.

impl HostMesh

pub fn set_bootstrap(&mut self, cmd: BootstrapCommand)

Set the bootstrap command on the underlying HostMeshRef, so that future spawn calls use it. Unlike HostMeshRef::with_bootstrap this mutates in place, preserving ownership.

Methods from Deref<Target = HostMeshRef>

pub async fn spawn<C: Actor>( &self, cx: &C, name: &str, per_host: Extent, proc_bind: Option<Vec<ProcBind>>, ) -> 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.

proc_bind, when provided, is a per-process CPU/NUMA binding configuration. Its length must equal the number of ranks in per_host. Each entry maps binding keys (cpunodebind, membind, physcpubind, cpus) to their values. Only takes effect when running on Linux.

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.

Trait Implementations

impl AsRef<HostMeshRef> for HostMesh

fn as_ref(&self) -> &HostMeshRef

Converts this type into a shared reference of the (usually inferred) input type.

impl Deref for HostMesh

type Target = HostMeshRef

The resulting type after dereferencing.

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

Dereferences the value.