Struct Executor 

pub struct Executor(/* private fields */);

Available on crate feature std only.

A configured command that reports process failures as ExecutorError.

Executables are looked up in the ASIMOV root’s libexec directory before falling back to the supplied program name or path. By default, all three standard streams are connected to the null device, NO_COLOR=1 is set, and spawned children are configured to be killed when their handles are dropped. Use command to customize these settings before execution.

Each execution spawns a new process using the stored command configuration. Stdout is returned only when configured as a pipe; otherwise the successful result is an empty cursor or stream. Captured stderr is included in process exit errors when it is valid UTF-8. ExecutionCompletion exposes exit status, input delivery, and diagnostics separately; its into_result method defines the error precedence used by the convenience APIs.

Example

Prepare a piped input and capture both output streams before spawning:

use asimov_runner::{Executor, Input};
use std::io::Cursor;

let mut input = Input::AsyncRead(Box::new(Cursor::new(b"example input".to_vec())));
let mut executor = Executor::new("asimov-example-reader");
executor.command().stdin(input.as_stdio());
executor.capture_stdout();
executor.capture_stderr();

let bytes = executor.execute_with_input(&mut input).await?.into_inner();

Implementations

impl Executor

pub fn new(program: impl AsRef<OsStr>) -> Self

Prepares a command with the executor’s default environment and streams.

If <asimov_root>/libexec/<program> exists, it is selected; otherwise program is passed to Tokio unchanged, allowing normal PATH lookup for a bare name. Existence does not guarantee that the selected file can be executed. Such errors are reported when the command is spawned.

pub fn with_batching(self, options: BatchOptions) -> Self

Configures batching for captured JSONL results, without changing the subprocess command or byte-oriented execution methods.

pub fn batch_options(&self) -> BatchOptions

The policy used for captured JSONL batches.

pub fn command(&mut self) -> &mut Command

Returns the underlying command for configuring arguments, environment, working directory, standard streams, or process-lifetime behavior.

pub fn ignore_stdin(&mut self)

Connects the child’s stdin to the null device, giving it immediate EOF.

pub fn ignore_stdout(&mut self)

Discards the child’s stdout by connecting it to the null device.

pub fn ignore_stderr(&mut self)

Discards the child’s stderr, leaving no diagnostic text to capture.

pub fn capture_stdout(&mut self)

Pipes stdout for buffered execution or live JSONL batch streaming.

pub fn capture_stderr(&mut self)

Pipes stderr so execution can attach its UTF-8 contents to exit errors.

pub async fn execute(&mut self) -> ExecutorResult

Spawns the command and waits for completion, returning captured stdout.

No input is written by this method. Use execute_with_input to copy an input stream into the child.

Errors

Returns an error if spawning or waiting fails, or if the child exits unsuccessfully. See ExecutorError for the error categories.

pub async fn execute_with_input(&mut self, input: &mut Input) -> ExecutorResult

Spawns the command, copies input into stdin, and waits for completion.

Configure stdin with input.as_stdio() through command before calling this method. Input::Ignored performs no copy and does not change the command’s stdin configuration. An asynchronous reader is normally consumed from its current position to EOF, then the stdin pipe is closed. Reusing the input does not rewind it or restore partly written bytes after early exit or cancellation.

Input is fed concurrently with draining stdout and stderr. JSONL input is coalesced per batch with backpressure and source error propagation. Early child exit cancels a pending input feed and is reported as ExecutorError::IncompleteInput on an otherwise successful exit. Use execute_with_io_completion to inspect intentional early exit. Success confirms EOF and delivery to the pipe, not application-level processing of the supplied data.

Errors

Returns an error if spawning, copying input, or waiting fails, or if the child exits unsuccessfully. Non-ignored input requires piped stdin; otherwise feeding it returns an I/O InvalidInput error.

pub async fn execute_with_io( &mut self, input: &mut Input, output: &mut Output, ) -> ExecutorResult

Feeds input and routes stdout concurrently, requiring complete delivery and a successful exit. Configure stdin/stdout from input.as_stdio() and output.as_stdio() first. Only Output::Captured returns payload bytes.

Errors

Returns spawn, transport, forwarding, input-delivery, or exit errors using the precedence documented by ExecutionCompletion::into_result.

pub async fn execute_with_io_completion( &mut self, input: &mut Input, output: &mut Output, ) -> Result<ExecutionCompletion, ExecutorError>

Executes with explicit exit and input-delivery outcomes.

Configure stdin/stdout from the supplied input/output policies before calling. Input and writers are borrowed and retained for reuse, without rewinding. Stdout forwarding and stderr collection run concurrently with feeding stdin and waiting for exit. Early exit cancels pending input; source errors terminate the child, while broken pipes allow it to finish naturally so its exit diagnostics are preserved. Ready input outcomes are polled before exit to give EOF and source errors consistent precedence.

Errors

Only spawn, stdout/stderr transport, writer, and wait failures are returned directly. Child exit and input failures are fields of the returned ExecutionCompletion, even when the exit status is unsuccessful.

pub async fn spawn(&mut self) -> Result<Child, ExecutorError>

Starts a new child process using the current command configuration.

The returned handle provides access to any piped standard streams. Unless overridden through command, dropping that handle before completion requests termination of that child, without waiting for it to be reaped or guaranteeing termination of its descendants.

Errors

Maps an I/O NotFound error to ExecutorError::MissingProgram and all other spawn errors to ExecutorError::SpawnFailure.

pub async fn wait(&mut self, process: Child) -> ExecutorResult

Collects the child’s remaining piped output and waits for it to exit.

Any stdin handle still owned by process is closed before waiting. On success, returns all captured stdout in a cursor positioned at zero. Streams whose handles were taken from the child are not collected here.

Errors

Returns ExecutorError::UnexpectedOther for I/O errors. An unsuccessful exit becomes ExecutorError::Failure for a recognized sysexits status or ExecutorError::UnexpectedFailure otherwise, with captured UTF-8 stderr attached. Stdout is not retained in either failure variant.

impl Executor

pub async fn execute_jsonl(&mut self) -> Result<JsonlStream, ExecutorError>

Spawns a program and streams its stdout as JSONL batches.

Uses the configured standard streams; stdout must be piped to yield batches. No input is written. Any piped stdin is closed when the stream is polled. Even with ignored or inherited stdout, consume the stream to completion to check process success. See JsonlStream for polling and drop behavior.

Errors

Spawn errors are returned directly; read, wait, and exit errors are stream items.

pub async fn execute_jsonl_with_input( &mut self, input: &mut Input, ) -> Result<JsonlStream, ExecutorError>

Spawns a program, feeding input concurrently with streaming its stdout.

After a successful spawn, ownership of input moves into the returned stream and it is replaced with Input::Ignored. Repeated execution does not replay input. No input is consumed on spawn failure. Configure the command’s stdin with Input::as_stdio before calling this method. Stdout and stderr handling also use the existing command configuration. Input::AsyncRead copies raw bytes; Input::Jsonl writes framed lines. This method does not automatically adapt byte input into JSONL.

Polling drives I/O; see JsonlStream for buffering and drop behavior. Early child completion cancels the input feed and reports ExecutorError::IncompleteInput if the child otherwise succeeded. Errors follow crate::ExecutionCompletion::into_result precedence.

Errors

Spawn errors are returned directly; input, read, wait, and exit errors are stream items. Non-ignored input requires piped stdin; otherwise feeding it reports an I/O InvalidInput error through the stream.

pub async fn execute_jsonl_with_output( &mut self, output: &mut Output, ) -> Result<JsonlStream, ExecutorError>

Spawns a graph producer with the supplied stdout policy and no input. Configure stdout with Output::as_stdio first. Forwarded output is written while the returned stream is polled and yields no payload items. Spawn errors are returned directly; subsequent failures are stream items.

pub async fn execute_jsonl_with_io( &mut self, input: &mut Input, output: &mut Output, ) -> Result<JsonlStream, ExecutorError>

Spawns a graph program with concurrent input and stdout routing.

Configure the command using the policies’ as_stdio methods first. Successful spawning transfers input and any output writer into the stream. Captured stdout yields batches using Self::batch_options; other modes yield only eventual errors. Complete lines buffered before an error are delivered as a partial batch first. A transferred writer is flushed at EOF, not shut down, and the wrapper’s output policy becomes Output::Ignored for subsequent executions. Non-writer output policies remain reusable. Spawn failure consumes neither.

Errors

Spawn errors are returned directly. Input, transport, writer, wait, and exit failures are stream items. Success requires complete input delivery and zero exit status; see crate::ExecutionCompletion::into_result.

Trait Implementations

impl Debug for Executor

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

Formats the value using the given formatter.