Struct PtySession 

pub struct PtySession { /* private fields */ }

A live, real-pseudo-terminal-backed child process.

The spawn/write/read/lifecycle plumbing capture_pty and examples/tests/support’s marker/settle-driven test harness both need, factored out so each keeps its own distinct polling loop on top of it. See this module’s docs for why the two loops aren’t shared too.

Implementations

impl PtySession

pub fn spawn( bin: &Path, args: &[&str], env: &[(&str, &str)], cols: u16, rows: u16, ) -> Result<Self>

Opens a colsxrows pseudo-terminal, spawns bin (with args and env, plus TERM=xterm-256color) on its slave side, and starts draining the master side’s output on a background thread into output.

Errors

Returns an error if the PTY can’t be opened, bin can’t be spawned, or the reader/writer handles can’t be obtained from the master side.

Panics

Never panics itself; the spawned background reader thread panics only if output’s lock is poisoned, which requires another panic while holding it first.

pub fn output(&self) -> Arc<Mutex<Vec<u8>>>

The shared output buffer, appended to by the background reader thread as bytes arrive. Lock it directly (rather than calling this repeatedly and cloning the whole capture) to scan or parse only the bytes that arrived since a caller’s own last poll.

pub fn reader_done(&self) -> Arc<Mutex<bool>>

Set once the background reader thread’s read returns EOF or an error: the child has closed the PTY and no more output will ever arrive. Useful as a non-blocking check before committing to a wait with its own timeout/diagnostics, which finish doesn’t provide (it blocks on the reader thread unconditionally).

pub fn write_all(&mut self, bytes: &[u8]) -> Result<()>

Writes bytes to the child’s PTY input.

Errors

Returns an error if the write half was already closed via close_writer, or if the underlying write fails (e.g. the child has exited and closed its end of the PTY).

pub fn close_writer(&mut self)

Closes the write half of the PTY, so the child sees EOF the next time it reads its stdin. Idempotent. finish always does this first; call it directly only to close the write half earlier (e.g. before a child that reacts to EOF on its own).

pub fn try_wait(&mut self) -> Result<Option<ExitStatus>>

Polls whether the child has exited, without blocking.

Errors

Returns an error if the underlying platform wait call fails.

pub fn kill(&mut self)

Sends the child a kill signal. Best-effort: a child that has already exited is not an error here.

pub fn wait(&mut self)

Blocks until the child exits. Best-effort: an already-reaped child is not an error here.

pub fn finish(self) -> Result<Vec<u8>>

Closes the write half (if still open) and blocks until the background reader thread has fully drained the output and returned, then hands back everything captured.

Errors

Returns an error if the reader thread itself panicked.

Panics

Panics if reader_handle is already None, which can’t happen through the public API – spawn always sets it, and finish is the only place that takes it.