Struct Running 

pub struct Running<'obs> { /* private fields */ }

A running sandbox.

Returned by Cage::spawn and Cage::spawn_with once the command is executing. The handle owns the caller side of the sandbox’s channels: waiting pumps captured output to the observer and collects the command’s exit status, terminate requests a graceful stop, and kill forcibly tears the sandbox down.

Waiting is fused: once the outcome is known, every further wait returns it without blocking.

Dropping the handle without waiting neither kills the sandbox (unless stop_with_caller is set, whose tie the drop severs) nor collects its outcome; without a PID namespace the supervisor process then remains a zombie child process of the caller until the caller exits. Prefer waiting — including after a kill.

The escalation recipe, for callers that need a bounded stop:

let mut running = cage.spawn()?;
let status = match running.wait_deadline(soft)? {
    Some(status) => status,
    None => {
        running.terminate()?; // SIGTERM: a chance to exit cleanly
        match running.wait_deadline(hard)? {
            Some(status) => status,
            None => {
                running.kill()?; // SIGKILL: tear the sandbox down
                running.wait()?
            }
        }
    }
};

Implementations

impl<'obs> Running<'obs>

pub fn pid(&self) -> u32

The host process id of the sandbox supervisor — the process this handle anchors on: the namespace init, or the command process itself without a PID namespace. Not the launch stage, which built the namespaces and, with a PID namespace, has already exited.

Informational — for signaling, use kill and terminate, which cannot hit a recycled pid.

pub fn wait(&mut self) -> Result<ExitStatus, Error>

Waits for the command to terminate, pumping captured output to the observer, and returns its exit status.

Like Cage::run, a non-zero exit is data, not an error. An error means the library failed to collect the outcome.

When output is captured, the wait completes once the command’s outcome is known and both captured streams have reached end-of-file. Under the default PID namespace, teardown at command exit closes the streams promptly. With pid_namespace(false), a descendant that outlives the command holds the streams open, and an unbounded wait blocks until the last holder closes them; a caller whose command may leave such descendants behind should prefer wait_deadline or wait_timeout.

pub fn wait_deadline( &mut self, deadline: Instant, ) -> Result<Option<ExitStatus>, Error>

Waits until the command terminates or the deadline passes.

Returns Ok(None) when the deadline passes first; the command keeps running, output produced before the deadline has been delivered, and the wait can be resumed. The deadline does not kill anything — escalation is the caller’s, per the recipe above.

pub fn wait_timeout( &mut self, timeout: Duration, ) -> Result<Option<ExitStatus>, Error>

wait_deadline with a relative timeout.

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

Requests graceful termination: SIGTERM to the command.

The signal is deliverable and trappable, docker-stop style; a command may clean up and exit, or may ignore it. Follow with a deadline and kill for a bounded stop. Requesting termination of a sandbox that has already exited is not an error.

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

Kills the sandbox: SIGKILL to the supervisor.

With a PID namespace this kills its init, and the kernel then kills every process in the namespace — nothing survives. Without one, only the command process itself is killed; descendants it spawned are beyond the library’s reach.

The kill is delivered through a pidfd and cannot hit a recycled pid. Killing a sandbox that has already exited is not an error. After a kill, wait still pumps the output produced before the kill and then reports the outcome.

The killed outcome is reported as signaled(SIGKILL) only once the signal is known delivered; the flag that carries that fact is set after the signal so a failed signal cannot fabricate a killed outcome. When a KillHandle on another thread issues the kill while this thread is waiting, that ordering leaves a narrow window in which the waiter can observe the supervisor’s death before the flag is set and report Error::SupervisorLost instead of signaled(SIGKILL). The kill still took effect; only the reported form differs, and only for a cross-thread kill racing the wait. A same-thread kill (this method before a subsequent wait) is not affected.

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

Returns a handle that can terminate or kill the sandbox from another thread, while this handle blocks in a wait.

Trait Implementations

impl Debug for Running<'_>

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

Formats the value using the given formatter.