crumbkit-process 0.3.0

Runs a child program in a process group of its own and reads its output within byte limits and a deadline
Documentation

crumbkit-process

crumbkit-process runs another program whose output a tool reads. It starts the child so that the child's descendants stop with it, reads standard output and standard error within byte limits and a deadline, stops the child gracefully before it kills it, and reaps it without signalling a process id that another process may have taken.

The crate depends on neither crumbkit nor crumbkit-child, because it prints nothing and parses no command line.

Adding it

[dependencies]
crumbkit-process = "0.3"

Example

A tool builds the command, states what it keeps of each stream and how long the child may run, and reads how the child ended:

use std::process::Command;
use std::time::{Duration, Instant};

use crumbkit_process::{Capture, Escalation, Outcome, OverLimit, RunError, RunOptions, Signal, Status};

fn version(mut tool: Command) -> Result<Option<Vec<u8>>, RunError> {
    tool.arg("--version");
    let settings = RunOptions::new()
        .stdout(Capture::Whole { limit: 64 * 1024, over: OverLimit::Stop })
        .stderr(Capture::Tail { limit: 4096 })
        .deadline(Instant::now() + Duration::from_secs(10))
        .escalation(Escalation::default().step(Signal::Terminate, Duration::from_secs(2)));
    let finished = crumbkit_process::run(tool, &settings)?;
    Ok(match finished.outcome() {
        Outcome::Ended(Status::Code(0)) => Some(finished.into_output().0.into_bytes()),
        _ => None,
    })
}

Capture::Lines delivers a stream line by line through a bounded queue from line_queue while the child runs, which the caller reads from another thread.

On Unix the child leads a new process group. On Windows it runs in a job object, and a stop ends the job at once with no graceful step. A tool that is killed outright or crashes leaves the job's processes running on Windows, and leaves the group running on Unix.

The off-by-default forward feature, on Unix only, stops every live child group when the tool receives SIGINT, SIGTERM or SIGHUP, runs the tool's clean-ups, and then ends the tool as the signal would have. A tool that also keeps crumbkit-usage's log starts it with start_under(forward::clean_up) before it registers any other clean-up, so the forwarder alone ends the tool and the log's line is its first clean-up.

Where to read more

  • run and RunOptions describe the one-shot run, its limits, deadline, cancel and scope, and Outcome how it ended. ChildFinished::status gives the child's own status, which a stopped run has too.
  • Escalation lists the steps that stop the child, and forward forwards the tool's signals.
  • The processes docs describe the current behaviour, and ADR-0171, ADR-0172 and ADR-0174 record why.

Licensed under either of Apache License, Version 2.0 or MIT license at your option.