Struct BootstrapProcManager

pub struct BootstrapProcManager { /* private fields */ }

A process manager for launching and supervising bootstrap processes (via the bootstrap entry point).

BootstrapProcManager is the host-side runtime for external procs in a hyperactor mesh. It spawns the configured bootstrap binary, forwards each child’s stdout/stderr into the logging channel, tracks lifecycle state through BootstrapProcHandle / ProcStatus, and ensures best-effort teardown on drop.

Internally it maintains two maps:

• [children]: async map from ProcId to BootstrapProcHandle, used for lifecycle queries (status) and exit monitoring.
• [pid_table]: synchronous map from ProcId to raw PIDs, used in Drop to synchronously send SIGKILL to any still-running children.

Together these provide both a queryable, real-time status surface and a deterministic cleanup path, so no child processes are left orphaned if the manager itself is dropped.

Implementations

impl BootstrapProcManager

pub fn command(&self) -> &BootstrapCommand

The bootstrap command used to launch processes.

pub fn socket_dir(&self) -> &Path

The socket directory, where per-proc Unix sockets are placed.

pub async fn status(&self, proc_id: &ProcId) -> Option<ProcStatus>

Return the current ProcStatus for the given ProcId, if the proc is known to this manager.

This queries the live BootstrapProcHandle stored in the manager’s internal map. It provides an immediate snapshot of lifecycle state (Starting, Running, Stopping, Stopped, etc.).

Returns None if the manager has no record of the proc (e.g. never spawned here, or entry already removed).

Trait Implementations

impl BulkTerminate for BootstrapProcManager

fn terminate_all<'life0, 'life1, 'async_trait>( &'life0 self, cx: &'life1 (impl 'async_trait + Actor), timeout: Duration, max_in_flight: usize, ) -> Pin<Box<dyn Future<Output = TerminateSummary> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Attempt to gracefully terminate all child procs managed by this BootstrapProcManager.

Each child handle is asked to terminate(timeout), which sends SIGTERM, waits up to the deadline, and escalates to SIGKILL if necessary. Termination is attempted concurrently, with at most max_in_flight tasks running at once.

Returns a TerminateSummary with counts of how many procs were attempted, how many successfully terminated (including those that were already terminal), and how many failed.

Logs a warning for each failure.

impl Debug for BootstrapProcManager

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for BootstrapProcManager

fn drop(&mut self)

Drop implementation for BootstrapProcManager.

Ensures that when the manager itself is dropped, any child processes it spawned are also terminated. This is a best-effort cleanup mechanism: the manager iterates over its recorded PID table and sends SIGKILL to each one.

Notes:

• Uses a synchronous Mutex so it can be locked safely in Drop without async context.
• Safety: sending SIGKILL is low-level but safe here because it only instructs the OS to terminate the process. The only risk is PID reuse, in which case an unrelated process might be signaled. This is accepted for shutdown semantics.
• This makes BootstrapProcManager robust against leaks: dropping it should not leave stray child processes running.

impl ProcManager for BootstrapProcManager

fn transport(&self) -> ChannelTransport

Return the ChannelTransport used by this proc manager.

For BootstrapProcManager this is always ChannelTransport::Unix, since all procs are spawned locally on the same host and communicate over Unix domain sockets.

fn spawn<'life0, 'async_trait>( &'life0 self, proc_id: ProcId, backend_addr: ChannelAddr, config: BootstrapProcConfig, ) -> Pin<Box<dyn Future<Output = Result<Self::Handle, HostError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Launch a new proc under this BootstrapProcManager.

Spawns the configured bootstrap binary (self.program) in a fresh child process. The environment is populated with variables that describe the bootstrap context — most importantly HYPERACTOR_MESH_BOOTSTRAP_MODE, which carries a base64-encoded JSON Bootstrap::Proc payload (proc id, backend addr, callback addr, optional config snapshot). Additional variables like BOOTSTRAP_LOG_CHANNEL are also set up for logging and control.

Responsibilities performed here:

• Create a one-shot callback channel so the child can confirm successful bootstrap and return its mailbox address plus agent reference.
• Spawn the OS process with stdout/stderr piped.
• Stamp the new BootstrapProcHandle as ProcStatus::Running once a PID is observed.
• Wire stdout/stderr pipes into local writers and forward them over the logging channel (BOOTSTRAP_LOG_CHANNEL).
• Insert the handle into the manager’s children map and start an exit monitor to track process termination.

Returns a BootstrapProcHandle that exposes the child process’s lifecycle (status, wait/ready, termination). Errors are surfaced as HostError.

type Handle = BootstrapProcHandle

Concrete handle type this manager returns.

type Config = BootstrapProcConfig

Additional configuration for the proc, supported by this manager.

impl SingleTerminate for BootstrapProcManager

fn terminate_proc<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, cx: &'life1 (impl 'async_trait + Actor), proc: &'life2 ProcId, timeout: Duration, ) -> Pin<Box<dyn Future<Output = Result<(Vec<ActorId>, Vec<ActorId>), Error>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Attempt to gracefully terminate one child procs managed by this BootstrapProcManager.

Each child handle is asked to terminate(timeout), which sends SIGTERM, waits up to the deadline, and escalates to SIGKILL if necessary. Termination is attempted concurrently, with at most max_in_flight tasks running at once.

Logs a warning for each failure.