Struct SubprocessExecutor 

pub struct SubprocessExecutor { /* private fields */ }

Subprocess executor

Manages a child process for executing compiled code with isolation. The subprocess binary implements the IPC protocol for loading libraries and executing functions.

Why Subprocess? (ODD-0038 Decision 3)

• Rust threads cannot be interrupted (no pthread_cancel)
• Ctrl-C support requires process isolation
• Crashes in user code don’t corrupt REPL state
• evcxr evidence: Subprocess from day one, never changed

IPC Protocol (ODD-0038 Decision 3a)

Commands (stdin):

• LOAD <path> - Load dynamic library
• RUN <cache_key> - Execute function from loaded library

Responses (stdout):

• LOADED - Library loaded successfully
• OXUR_EXECUTION_COMPLETE - Execution finished
• OXUR_RUNTIME_ERROR <msg> - Runtime error
• OXUR_PANIC_LOCATION <info> - Panic with location

Status

Phase 1 STUB: Manages subprocess lifecycle but doesn’t execute yet. Full IPC implementation coming in Phase 2.

Examples

use oxur_repl::executor::SubprocessExecutor;
use std::path::PathBuf;

// Create executor (spawns subprocess)
let mut executor = SubprocessExecutor::new()?;

// Load a library (Phase 2)
// executor.load_library(&PathBuf::from("path/to/lib.so"))?;

// Execute code (Phase 2)
// let result = executor.execute("cache_key_123")?;

// Shutdown
executor.shutdown()?;

Implementations

impl SubprocessExecutor

pub fn new() -> Result<Self, ExecutorError>

Create a new subprocess executor

Spawns the subprocess binary and establishes IPC connection.

Errors

Returns error if subprocess cannot be spawned

pub fn is_loaded(&self, cache_key: impl AsRef<str>) -> bool

Check if a library is already loaded

pub fn load_library( &mut self, path: &Path, cache_key: impl AsRef<str>, ) -> Result<(), ExecutorError>

Load a dynamic library into the subprocess

Sends a LOAD command via IPC and waits for confirmation.

Arguments

• path - Path to dynamic library (.so/.dylib/.dll)
• cache_key - Cache key for tracking loaded state

Errors

Returns error if:

• Subprocess is not running
• LOAD command fails to send
• Library fails to load in subprocess
• Response parsing fails

pub fn execute( &mut self, cache_key: impl AsRef<str>, ) -> Result<ExecutionResult, ExecutorError>

Execute compiled code from a loaded library

Sends a RUN command via IPC and parses the execution result.

Arguments

• cache_key - Cache key identifying the function to execute

Errors

Returns error if:

• Subprocess is not running
• RUN command fails to send
• Response parsing fails

Returns

Returns ExecutionResult with success, runtime error, or panic information

pub fn shutdown(&mut self) -> Result<Option<ExitStatus>, ExecutorError>

Shutdown the subprocess

Closes stdin and waits for subprocess to exit.

Returns the exit status if the subprocess was running, None otherwise.

pub fn restart(&mut self) -> Result<RestartReason, ExecutorError>

Restart the subprocess

Useful for recovering from crashes or clearing state. Records the restart reason in metrics based on exit status.

Returns the restart reason determined from exit status.

pub fn restart_user_requested(&mut self) -> Result<(), ExecutorError>

Restart the subprocess due to user request

Records the restart as user-requested in metrics.

pub fn loaded_count(&self) -> usize

Get count of loaded libraries

pub fn is_running(&self) -> bool

Check if subprocess is running

pub fn uptime_seconds(&self) -> f64

Get the current subprocess uptime in seconds

pub fn restart_count(&self) -> u64

Get the total restart count

pub fn update_metrics(&self)

Update the uptime gauge in metrics

Should be called periodically to keep the metrics current.

pub fn metrics(&self) -> &SubprocessMetrics

Get a reference to the subprocess metrics

Trait Implementations

impl Debug for SubprocessExecutor

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

Formats the value using the given formatter.

impl Drop for SubprocessExecutor

fn drop(&mut self)

Executes the destructor for this type.