Struct SpawnOptionsBuilder 

pub struct SpawnOptionsBuilder { /* private fields */ }

Builder for SpawnOptions.

Move-only when SpawnOptionsBuilder::pty_with has been called: the builder then owns a pty pair, so it is not Clone (see SpawnOptions).

Implementations

impl SpawnOptionsBuilder

pub fn new(argv: Vec<String>, backend: SpawnBackend) -> Self

Create a new builder with the specified argument vector.

pub fn env(self, env: Vec<String>) -> Self

Set environment variables.

pub fn cwd(self, cwd: String) -> Self

Set the working directory.

pub fn stdin(self, data: impl Into<Box<[u8]>>) -> Self

Provide data to be written to the child’s stdin.

pub fn capture_stdout(self) -> Self

Enable stdout capture.

pub fn capture_stderr(self) -> Self

Enable stderr capture.

pub fn wait(self, wait: bool) -> Self

Set whether to wait for the process to terminate (default: true).

pub fn pgroup(self, pgroup: ProcessGroup) -> Self

Set process group and isolation policy.

pub fn session_containment(self) -> Self

Contain the child inside the process group/session it is placed into.

A seccomp filter installed in the child (after the daemon’s own setsid/setpgid, before execve) denies setsid, setpgid, setpgrp, unshare, and setns. Because filters are inherited across fork and execve and can only be tightened, never loosened, the child and every descendant are locked into the group/session — making kill_group (timeout/cancel deactivation) total even against a hostile root child that tries to escape by daemonizing or changing its process group. Requires an isolated process group (ProcessGroup::new(None, true)); rejected on SpawnBackend::PosixSpawn, which has no child setup step.

pub fn max_output(self, max: usize) -> Self

Set the combined stdout+stderr output buffer size (default: 1MB).

If captured output exceeds this limit, spawn drains the child pipes to completion and returns EOVERFLOW.

pub fn timeout_ms(self, ms: u32) -> Self

Set the execution timeout in milliseconds.

pub fn kill_grace_ms(self, ms: u32) -> Self

Set the grace period before SIGKILL (default: 2s).

pub fn cancel(self, policy: CancelPolicy) -> Self

Set the cancellation policy (default: Kill).

pub fn fd_policy(self, policy: SpawnFdPolicy) -> Self

Set the child file-descriptor inheritance policy.

pub fn early_exit(self, callback: fn(&[u8]) -> bool) -> Self

Set an early exit callback.

pub fn chunk_sink<F>(self, sink: F) -> Self

where F: Fn(bool, &[u8]) -> SinkResult + Send + Sync + 'static,

Enable streaming drain: forward every retained output chunk to sink as it is read instead of accumulating it for the completion Output.

The sink returns SinkResult::Pause when its bounded queue is full; the drain then stops reading the child (kernel backpressure applies) without dropping the held chunk and without blocking the reactor. Resume via the managed-process or drain resume methods once the queue drains. When a sink is set, max_output no longer truncates: bytes are never dropped on the streaming path.

pub fn pty(self) -> Self

Spawn the child on a pseudo-terminal (see SpawnOptions::pty).

Mutually exclusive with pipe capture: the slave replaces capture_stdout/capture_stderr/stdin as the child’s stdio, and the master replaces the stdout pipe on the drain (single merged stream).

Core creates the pty pair internally. To pre-configure the pty window before the child execs (and derive the child’s terminal env from the read-back), use SpawnOptionsBuilder::pty_with instead — it takes a caller-created pair and is move-only.

pub fn pty_with(self, master: Fd, slave: Fd) -> Self

Spawn the child on a pseudo-terminal using a caller-created pty pair, whose initial window the caller already configured.

The typical flow:

1. make_pty returns (master, slave);
2. pty_window applies the initial size to the master and reads back the actual winsize;
3. the caller derives LINES/COLUMNS from that read-back;
4. this method hands ownership of the pair to Core.

Core takes ownership of both descriptors and is responsible for their cleanup on every spawn success/failure path. The builder (and the resulting SpawnOptions) is move-only from this point — a pty pair is not Cloneable, so neither is the builder that owns it.

pub fn pdeath_signal(self, sig: i32) -> Self

Arm PR_SET_PDEATHSIG on the spawned child (opt-in).

When set, the child receives sig when the parent thread that created it exits (see SpawnOptions::pdeath_signal for the exact semantics and scope). The child arms the signal before any other setup and aborts if getppid() no longer matches its expected parent — closing the fork→prctl race that would otherwise leave the signal silently undelivered.

pub fn session_exit(self, policy: SessionExitPolicy) -> Self

Set the natural-exit policy for a contained session (see SessionExitPolicy). Defaults to SessionExitPolicy::Sweep.

pub fn build(self) -> Result<SpawnOptions, CoreError>

Build the spawn options.