Module host

This module defines Host, which represents all the procs running on a host. The procs themselves are managed by an implementation of ProcManager, which may, for example, fork new processes for each proc, or spawn them in the same process for testing purposes.

The primary purpose of a host is to manage the lifecycle of these procs, and to serve as a single front-end for all the procs on a host, multiplexing network channels.

Channel muxing

A Host maintains a single frontend address, through which all procs are accessible through direct addressing: the id of each proc is the ProcId::Direct(frontend_addr, proc_name). In the following, the frontend address is denoted by *. The host listens on * and multiplexes messages based on the proc name. When spawning procs, the host maintains backend channels with separate addresses. In the diagram # is the backend address of the host, while #n is the backend address for proc n. The host forwards messages to the appropriate backend channel, while procs forward messages to the host backend channel at #.

                     ┌────────────┐
                 ┌───▶  proc *,1  │
                 │ #1└────────────┘
                 │
 ┌──────────┐    │   ┌────────────┐
 │   Host   │◀───┼───▶  proc *,2  │
*└──────────┘#   │ #2└────────────┘
                 │
                 │   ┌────────────┐
                 └───▶  proc *,3  │
                   #3└────────────┘

Modules

testing

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

Structs

Host

A host, managing the lifecycle of several procs, and their backend routing, as described in this module’s documentation.

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).

TerminateSummary

Summary of results from a bulk termination attempt.

Enums

HostError

The type of error produced by host operations.

ReadyError

Error returned by ProcHandle::ready.

TerminateError

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

WaitError

Error returned by ProcHandle::wait.

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.

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.