Skip to main content

Crate crumbkit_process

Crate crumbkit_process 

Source
Expand description

§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.1"

§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, Exit, OverLimit, Run, RunError, Signal};

fn version(mut tool: Command) -> Result<Option<Vec<u8>>, RunError> {
    tool.arg("--version");
    let settings = Run::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.exit() {
        Exit::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.

§Where to read more

  • run and Run describe the one-shot run, its limits, deadline, cancel and scope, and Exit how it ended. Finished::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.

Modules§

forward
Stops every live child group when the tool itself receives SIGINT, SIGTERM or SIGHUP, runs the tool’s clean-ups, and then takes the signal’s default action. It exists on Unix with the forward feature.

Structs§

Cancel
A handle that stops the runs that watch it.
Captured
What a run kept of one output stream.
Escalation
How a run stops its child: each step sends a signal to the group and waits its grace for the child to exit, and a kill follows the last step.
Finished
How a run’s child ended and what the run kept of its output.
LineQueue
The side of a line queue that a run fills. A run takes it in Capture::Lines.
Lines
The caller’s side of a line queue, which yields each line of the stream without its newline as the run reads it. Dropping it tells the run that nobody reads the lines, and the run reads the rest of the stream and drops it.
Run
The settings of one run: the child’s input, what it keeps of each output stream, when and how it stops the child, and the child’s scope.
Silent
No line arrived and the run did not end within the time that Lines::recv_timeout waited.

Enums§

Capture
What a run keeps of one output stream of the child.
Exit
How a run’s child ended. The caller can tell an exit, a signal, a timeout and a stop apart. Finished::status gives the child’s own status as the run reaped it, which a timeout or a stop also has.
Input
What the child reads on its standard input.
OverLimit
What a run does when a stream that it keeps whole or as lines passes its limit.
RunError
A run that could not start its child or follow it to its end.
Scope
Which processes a run holds and signals.
Signal
A signal that a run sends to the processes in its scope.
Status
How the child process itself ended, as the run reaped it. A run that stopped the child gives the status that the stop caused, such as the signal of its first step or the code that the child’s handler of that signal exited with.
Stop
Why a run stopped its child before its deadline.

Constants§

DRAIN_GRACE
How long a run keeps reading the child’s pipes after it reaps the child. A descendant outside the child’s scope that holds a pipe open holds the run no longer than this.

Functions§

line_queue
Returns a queue that holds at most most lines, or one line when most is 0: the side that a run fills, which Capture::Lines takes, and the caller’s side.
run
Runs command with the settings of run and returns how it ended and what it printed.