Struct ProcessService 

pub struct ProcessService { /* private fields */ }

Process service for managing child processes

This is a thin wrapper around the runtime’s ProcessManager, adding CLI-specific conveniences and delegating core functionality to the runtime layer.

Examples

use mecha10_cli::services::ProcessService;

let mut service = ProcessService::new();

// Spawn a node process
service.spawn_node("camera_driver", "target/debug/camera_driver", &[])?;

// Check status
let status = service.get_status();
println!("Running processes: {:?}", status);

// Stop a specific process
service.stop("camera_driver")?;

// Cleanup all processes
service.cleanup();

Implementations

impl ProcessService

pub fn build_node(&self, node_name: &str, release: bool) -> Result<()>

Build a node binary if needed

Helper method to build a specific node package

Arguments

• node_name - Name of the node to build
• release - Whether to build in release mode

pub fn build_all(&self, release: bool) -> Result<()>

Build all nodes in the workspace

Arguments

• release - Whether to build in release mode

impl ProcessService

pub fn get_status(&mut self) -> HashMap<String, String>

Get status of all processes

Returns a HashMap mapping process names to status strings

pub fn stop(&mut self, name: &str) -> Result<()>

Stop a specific process by name

Arguments

• name - Name of the process to stop

Errors

Returns an error if the process is not found

Note: This uses a default 10-second timeout for graceful shutdown. Use stop_with_timeout() for custom timeout.

pub fn stop_with_timeout(&mut self, name: &str, timeout: Duration) -> Result<()>

Stop a process with timeout for graceful shutdown

Tries graceful shutdown (SIGTERM on Unix), then force kills after timeout

Arguments

• name - Name of the process to stop
• timeout - How long to wait for graceful shutdown

Errors

Returns an error if process not found or cannot be stopped

pub fn force_kill(&mut self, name: &str) -> Result<()>

Force kill a process by name

Arguments

• name - Name of the process to kill

pub fn cleanup(&mut self)

Stop all processes gracefully in dependency order

This delegates to the runtime’s ProcessManager which handles:

• Dependency-based shutdown ordering
• Graceful shutdown with timeout
• Force kill fallback

pub fn is_running(&mut self, name: &str) -> bool

Check if a process is running

Arguments

• name - Name of the process to check

pub fn restart( &mut self, name: &str, binary_path: &str, args: &[&str], ) -> Result<u32>

Restart a specific process

Stops the process if running and starts it again

Arguments

• name - Name of the process
• binary_path - Path to the binary
• args - Command-line arguments

pub fn restart_all( &mut self, nodes: Vec<(&str, &str, Vec<&str>)>, ) -> Result<HashMap<String, u32>>

Restart all processes

Arguments

• nodes - Vec of (name, binary_path, args) tuples

impl ProcessService

pub fn find_global_binary(node_name: &str) -> Option<PathBuf>

Find globally installed binary for a node

Searches in:

1. ~/.cargo/bin/{node_name}
2. ~/.mecha10/bin/{node_name}

Arguments

• node_name - Name of the node (e.g., “camera”)

Returns

Path to the binary if found, None otherwise

pub fn resolve_node_binary( node_name: &str, is_monorepo_node: bool, project_name: &str, ) -> String

Resolve binary path for a node with smart resolution

Resolution strategy:

1. If global binary exists: use global binary
2. Fallback: use local build path

Arguments

• node_name - Name of the node
• is_monorepo_node - Whether this is a framework node
• project_name - Name of the project

Returns

Path to the binary to execute

pub fn resolve_node_runner_path() -> String

Resolve path to mecha10-node-runner binary

Resolution strategy:

1. Global installation: ~/.cargo/bin/mecha10-node-runner
2. Fallback: “mecha10-node-runner” (rely on PATH)

Returns

Path to the mecha10-node-runner binary

pub fn is_node_runner_available() -> bool

Check if mecha10-node-runner is available

impl ProcessService

pub fn spawn_node( &mut self, name: &str, binary_path: &str, args: &[&str], ) -> Result<u32>

Spawn a node process

Arguments

• name - Name to identify the process
• binary_path - Path to the binary to execute
• args - Command-line arguments

Errors

Returns an error if the process cannot be spawned

pub fn spawn_with_output( &mut self, name: &str, binary_path: &str, args: &[&str], ) -> Result<u32>

Spawn a process with output capture

Arguments

• name - Name to identify the process
• binary_path - Path to the binary to execute
• args - Command-line arguments

Errors

Returns an error if the process cannot be spawned

pub fn spawn_with_env( &mut self, name: &str, binary_path: &str, args: &[&str], env: HashMap<String, String>, ) -> Result<u32>

Spawn a process with custom environment variables

Arguments

• name - Name to identify the process
• binary_path - Path to the binary to execute
• args - Command-line arguments
• env - Environment variables to set

pub fn spawn_in_dir( &mut self, name: &str, binary_path: &str, args: &[&str], working_dir: impl AsRef<Path>, ) -> Result<u32>

Spawn a process in a specific working directory

Arguments

• name - Name to identify the process
• binary_path - Path to the binary to execute
• args - Command-line arguments
• working_dir - Working directory for the process

pub fn spawn_nodes( &mut self, nodes: Vec<(&str, &str, Vec<&str>)>, ) -> Result<HashMap<String, u32>>

Spawn multiple node processes from a list

Arguments

• nodes - Vec of (name, binary_path, args) tuples

Returns

HashMap of node names to PIDs

impl ProcessService

pub fn spawn_node_runner( &mut self, node_identifier: &str, project_name: &str, project_env: Option<HashMap<String, String>>, ) -> Result<u32>

Spawn a node using mecha10-node-runner

This is the simplified spawning method for Phase 2+ of Node Lifecycle Architecture. It delegates all complexity (binary resolution, model pulling, env setup) to node-runner.

Returns

Process ID of the spawned node-runner instance

Errors

Returns an error if the node-runner cannot be spawned

Configuration

The node-runner reads configuration from the node’s config file (e.g., configs/nodes/{node_name}.json) and supports the following runtime settings:

{
  "runtime": {
    "restart_policy": "on-failure",  // never, on-failure, always
    "max_retries": 3,
    "backoff_secs": 1
  },
  "depends_on": ["camera", "lidar"],
  "startup_timeout_secs": 30
}

To enable dependency checking, use: mecha10-node-runner --wait-for-deps <node-name>

Arguments

• node_identifier - Full node identifier (e.g., @mecha10/simulator, my-node)
• project_name - Name of the current project, forwarded to node-runner as --project. Without this, node-runner falls back to guessing the project name from its own current working directory’s basename (see its resolve_node_execution) to find the monorepo project binary at target/{release,debug}/{project_name} - a guess that silently breaks whenever the working directory’s name doesn’t match the actual Cargo package/binary name (e.g. a checkout cloned into a differently-named directory). That misresolution is what made bundled framework nodes (@mecha10/*) appear to fail under node-runner: with no monorepo binary found under the guessed name, node-runner falls through to its bundled-node fallback, which shells out to the globally installed mecha10 CLI as mecha10 node <name> - a subcommand the mecha10 CLI binary (packages/cli) doesn’t define, so that fallback always fails too. Passing the real project name explicitly removes the guess entirely.

pub fn spawn_node_direct( &mut self, node_identifier: &str, _project_name: &str, project_env: Option<HashMap<String, String>>, ) -> Result<u32>

Spawn a node directly (standalone mode)

This is used when mecha10-node-runner is not available (standalone projects installed from crates.io). Handles both framework nodes (via BinaryManager) and local project nodes (built and run directly).

Resolution strategy for framework nodes:

1. Check ~/.mecha10/bin/ for pre-downloaded binary
2. If not found, attempt to download from GitHub releases
3. If download fails, fall back to cargo install

Arguments

• node_name - Name of the node to run
• project_name - Name of the project (used to find the binary)
• project_env - Optional additional environment variables from project config

Returns

Process ID of the spawned node process

impl ProcessService

pub fn new() -> Self

Create a new process service

pub fn track_dependency(&mut self, node: &str, dependencies: Vec<String>)

Track dependency relationship for a node

Arguments

• node - Name of the node
• dependencies - List of nodes this node depends on

pub fn get_shutdown_order(&self) -> Vec<String>

Get shutdown order (reverse dependency order)

Returns nodes in order they should be stopped:

• Nodes with dependents first (high-level nodes)
• Then their dependencies (low-level nodes)

This ensures we don’t stop a node while other nodes depend on it.

Delegates to the runtime’s ProcessManager.

pub fn count(&self) -> usize

Get the number of tracked processes

pub fn is_empty(&self) -> bool

Check if any processes are being tracked

pub fn manager(&mut self) -> &mut ProcessManager

Get access to the underlying ProcessManager

Useful for advanced operations or when migrating existing code. Provides direct access to the runtime’s ProcessManager.

Trait Implementations

impl Default for ProcessService

fn default() -> Self

Returns the “default value” for a type.

impl Drop for ProcessService

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.