Skip to main content

ProcessExecutor

ralph_workflow

Trait ProcessExecutor 

Source 
pub trait ProcessExecutor:
    Send
    + Sync
    + Debug {
    // Required method
    fn execute(
        &self,
        command: &str,
        args: &[&str],
        env: &[(String, String)],
        workdir: Option<&Path>,
    ) -> Result<ProcessOutput>;

    // Provided methods
    fn spawn(
        &self,
        command: &str,
        args: &[&str],
        env: &[(String, String)],
        workdir: Option<&Path>,
    ) -> Result<SpawnedProcess> { ... }
    fn spawn_agent(&self, config: &AgentSpawnConfig) -> Result<AgentChildHandle> { ... }
    fn command_exists(&self, command: &str) -> bool { ... }
    fn get_child_process_info(&self, parent_pid: u32) -> ChildProcessInfo { ... }
    fn kill_process_group(&self, _pgid: u32) -> Result<()> { ... }
}
Expand description

Trait for executing external processes.

This trait abstracts process execution to allow dependency injection. Production code uses RealProcessExecutor which calls actual commands. Test code can use MockProcessExecutor to control process behavior.

Only external process execution is abstracted. Internal code logic is never mocked.

Required Methods§

Source

fn execute( &self, command: &str, args: &[&str], env: &[(String, String)], workdir: Option<&Path>, ) -> Result<ProcessOutput>

Execute a command with given arguments and return its output.

§Arguments
  • command - The program to execute
  • args - Command-line arguments to pass to the program
  • env - Environment variables to set for the process (optional)
  • workdir - Working directory for the process (optional)
§Returns

Returns a ProcessOutput containing exit status, stdout, and stderr.

§Errors

Returns an error if command cannot be spawned or if output capture fails.

Provided Methods§

Source

fn spawn( &self, command: &str, args: &[&str], env: &[(String, String)], workdir: Option<&Path>, ) -> Result<SpawnedProcess>

Spawn a process with stdin input and return a handle for interaction.

This method is used when you need to write to the process’s stdin. Unlike execute(), this returns a SpawnedProcess handle that exposes only the domain-relevant surface (stdin writing and process completion).

§Arguments
  • command - The program to execute
  • args - Command-line arguments to pass to the program
  • env - Environment variables to set for the process (optional)
  • workdir - Working directory for the process (optional)
§Returns

Returns a SpawnedProcess handle for writing stdin and waiting.

§Errors

Returns an error if command cannot be spawned.

Source

fn spawn_agent(&self, config: &AgentSpawnConfig) -> Result<AgentChildHandle>

Spawn an agent process with streaming output support.

This method is specifically designed for spawning AI agent subprocesses that need to output streaming JSON in real-time. Unlike spawn(), this returns a handle with boxed stdout for trait object compatibility.

§Arguments
  • config - Agent spawn configuration including command, args, env, prompt, etc.
§Returns

Returns an AgentChildHandle with stdout, stderr, and the child process.

§Errors

Returns an error if the agent cannot be spawned.

§Default Implementation

The default implementation spawns the agent command directly. Mock implementations should override this to return mock results without spawning real processes.

Source

fn command_exists(&self, command: &str) -> bool

Check if a command exists and can be executed.

This is a convenience method that executes a command with a --version or similar flag to check if it’s available.

§Arguments
  • command - The program to check
§Returns

Returns true if command exists, false otherwise.

Source

fn get_child_process_info(&self, parent_pid: u32) -> ChildProcessInfo

their cumulative CPU time.

Used by the idle-timeout monitor to determine whether child processes are actively working (CPU time advancing between consecutive checks) versus merely existing (stalled, zombie, or idle daemon).

Default implementation: parses ps output for PID, PPID, and cputime columns on Unix platforms. Returns ChildProcessInfo::NONE on non-Unix.

Any execution error is treated as “no children” to avoid blocking the timeout system. If ps is unavailable or fails unexpectedly, a one-time warning is emitted to stderr so operators can diagnose reduced protection against false-positive idle kills.

Source

fn kill_process_group(&self, _pgid: u32) -> Result<()>

Kill an entire process group by sending SIGKILL to all members.

Uses kill(-pid, SIGKILL) to send the signal to all processes in the process group identified by pgid. This is a best-effort fire-and-forget call; errors are ignored because the primary process has already exited.

The default implementation is a no-op so existing mock implementations continue to compile without change. The RealProcessExecutor override issues the actual SIGKILL.

Implementors§