Struct SpawnedProcess 

pub struct SpawnedProcess { /* private fields */ }

Handle to one or more spawned subprocesses (a single command or a pipeline).

Lifecycle methods (wait, kill, try_wait, wait_timeout) take &self so the handle can be shared across threads. Stdio accessors (take_stdin, take_stdout) are one-shot — the second call returns None.

For pipelines, take_stdin targets the leftmost stage, take_stdout the rightmost, and wait/kill operate on every stage. Exit status follows pipefail semantics: rightmost non-success wins.

Wait idempotency

wait, try_wait, and wait_timeout are all idempotent. The first finalize captures stdout, stderr, and per-stage exit statuses into an internal Arc; subsequent calls reconstruct the same Result<RunOutput, RunError> from that cache. This matters for:

• tokio::select!-style cancellation where a pending wait future is dropped and a second wait is issued after kill.
• Retry loops over a spawned handle.
• Concurrent wait calls from multiple threads — internal serialization ensures both see the same outcome, not split-brain partial state.

Cost of the second call: one Vec<u8> clone and one String clone per invocation (the cached raw bytes are copied into a fresh RunOutput). For multi-gigabyte outputs this is not free, but the common cases (accidental double-call, cancellation pattern) are cheap.

Dropping without waiting

Dropping a SpawnedProcess without calling wait leaves the child(ren) to be reaped by the OS; a valid pattern for fire-and-forget jobs but may leave short-lived zombies until parent exit on Unix.

Implementations

impl SpawnedProcess

pub fn command(&self) -> &CmdDisplay

Snapshot of the command used to spawn (shell-quoted, secret-redacted).

pub fn is_pipeline(&self) -> bool

Whether this handle represents a multi-stage pipeline.

pub fn take_stdin(&self) -> Option<ChildStdin>

Take ownership of the leftmost child’s stdin. Returns None after the first call or if stdin wasn’t piped. Drop the returned ChildStdin to send EOF.

pub fn take_stdout(&self) -> Option<ChildStdout>

Take ownership of the rightmost child’s stdout. Returns None after the first call or once the Read impl has consumed stdout.

pub fn pids(&self) -> Vec<u32>

All pids, leftmost-first. For a single command, length 1.

pub fn kill(&self) -> Result<(), Error>

Send SIGKILL (Unix) or TerminateProcess (Windows) to every stage. Returns the first error encountered, if any; still attempts all.

pub fn try_wait(&self) -> Result<Option<RunOutput>, RunError>

Non-blocking status check. Ok(None) means at least one stage is still running; only returns Ok(Some(_)) when every stage has exited. Idempotent — after the first Ok(Some(_)), subsequent calls return the same cached outcome.

pub fn wait(&self) -> Result<RunOutput, RunError>

Block until every stage exits, then assemble a RunOutput or RunError::NonZeroExit using pipefail status precedence. Idempotent — subsequent calls return the same cached outcome.

pub fn wait_timeout( &self, timeout: Duration, ) -> Result<Option<RunOutput>, RunError>

Wait up to timeout. Ok(None) means at least one stage is still running after the timeout — caller decides whether to kill or wait again. Idempotent once all stages have exited.

Trait Implementations

impl Debug for SpawnedProcess

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

Formats the value using the given formatter.

impl Read for &SpawnedProcess

Dual impl enabling (&proc).read(…). Lets one thread read while another holds the handle by reference and calls kill or wait.

fn read(&mut self, buf: &mut [u8]) -> Result<usize, Error>

Pull some bytes from this source into the specified buffer, returning how many bytes were read.

fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize, Error>

Like read, except that it reads into a slice of buffers.

fn is_read_vectored(&self) -> bool

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

Determines if this Reader has an efficient read_vectored implementation.

fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize, Error>

Reads all bytes until EOF in this source, placing them into buf.

fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>

Reads all bytes until EOF in this source, appending them to buf.

fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>

Reads the exact number of bytes required to fill buf.

fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> Result<(), Error>

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

Pull some bytes from this source into the specified buffer.

fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> Result<(), Error>

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

Reads the exact number of bytes required to fill cursor.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adapter for this instance of Read.

fn bytes(self) -> Bytes<Self>

where Self: Sized,

Transforms this Read instance to an Iterator over its bytes.

fn chain<R>(self, next: R) -> Chain<Self, R>

where R: Read, Self: Sized,

Creates an adapter which will chain this stream with another.

fn take(self, limit: u64) -> Take<Self>

where Self: Sized,

Creates an adapter which will read at most limit bytes from it.

fn read_array<const N: usize>(&mut self) -> Result<[u8; N], Error>

where Self: Sized,

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

Read and return a fixed array of bytes from this source.

impl Read for SpawnedProcess

Read directly from the rightmost stage’s stdout.

On first read, takes ownership of stdout internally (so subsequent take_stdout calls return None). Reads return Ok(0) when stdout closes (EOF). Call wait after EOF to surface the exit status.

fn read(&mut self, buf: &mut [u8]) -> Result<usize, Error>

Pull some bytes from this source into the specified buffer, returning how many bytes were read.

fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize, Error>

Like read, except that it reads into a slice of buffers.

fn is_read_vectored(&self) -> bool

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

Determines if this Reader has an efficient read_vectored implementation.

fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize, Error>

Reads all bytes until EOF in this source, placing them into buf.

fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>

Reads all bytes until EOF in this source, appending them to buf.

fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>

Reads the exact number of bytes required to fill buf.

fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> Result<(), Error>

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

Pull some bytes from this source into the specified buffer.

fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> Result<(), Error>

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

Reads the exact number of bytes required to fill cursor.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adapter for this instance of Read.

fn bytes(self) -> Bytes<Self>

where Self: Sized,

Transforms this Read instance to an Iterator over its bytes.

fn chain<R>(self, next: R) -> Chain<Self, R>

where R: Read, Self: Sized,

Creates an adapter which will chain this stream with another.

fn take(self, limit: u64) -> Take<Self>

where Self: Sized,

Creates an adapter which will read at most limit bytes from it.

fn read_array<const N: usize>(&mut self) -> Result<[u8; N], Error>

where Self: Sized,

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

Read and return a fixed array of bytes from this source.