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.4"§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, RunError, RunOptions, Signal, Status};
fn version(mut tool: Command) -> Result<Option<Vec<u8>>, RunError> {
tool.arg("--version");
let settings = RunOptions::new()
.stdout(Capture::whole(64 * 1024))
.stderr(Capture::tail(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
runandRunOptionsdescribe the one-shot run, its limits, deadline, cancel and scope, andOutcomehow it ended.ChildFinished::statusgives the child’s own status, which a stopped run has too.Escalationlists the steps that stop the child, andforwardforwards the tool’s signals.RunOptions::overduereports a child that still runs at a time and keeps waiting, so a tool that must never signal its child needs no wait loop.- 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
forwardfeature.
Structs§
- Cancel
- A handle that stops the runs that watch it.
- Capture
- What a run keeps of one output stream of the child.
- Captured
- What a run kept of one output stream.
- Child
Finished - How a run’s child ended and what the run kept of its output.
- 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.
- Line
Capture - A capture that delivers a stream as lines, from
Capture::lines. - Line
Queue - 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 end byte 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.
- Overdue
- What a run tells
RunOptions::overdue’s report: the child is still running at the overdue time. - RunOptions
- 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_timeoutwaited. - Spawn
- The start of one run’s child, which a hook set with
RunOptions::around_spawnreceives. - Spawned
- A child that
Spawn::startstarted, which a hook returns to the run. - Whole
Capture - A capture that keeps the first bytes of a stream, from
Capture::whole. - Zeroizing
Zeroizingis a wrapper for anyZ: Zeroizetype which implements aDrophandler which zeroizes dropped values.
Enums§
- Input
- What the child reads on its standard input.
- Long
Line - What a line longer than the limit of one line does to a stream delivered as lines.
- Outcome
- How a run’s child ended. The caller can tell an exit, a signal, a
timeout and a stop apart.
ChildFinished::statusgives the child’s own status as the run reaped it, which a timeout or a stop also has. - Over
Limit - 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
Reason - 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.
- REAP_
GRACE - How long after the child exits a run on Unix waits for the child’s group to be empty. On macOS the run also kills the group again while a live process is left. A process of the group that outlasts it is left behind and the run goes on to read the pipes: one that waits for a parent that never reaps it, or a live one that the tool may not signal, such as a setuid program.
Functions§
- line_
queue - Returns a queue that holds at most
mostlines, or one line whenmostis 0: the side that a run fills, whichCapture::linestakes, and the caller’s side. - run
- Runs
commandwith the settings inoptionsand returns how it ended and what it printed.