processkit

Child-process management for Rust, in two layers:

Process groups (ProcessGroup) — spawn a child as the root of a process tree that is killed as a unit when the group is dropped, using Windows Job Objects and Linux cgroup v2 (with a POSIX process-group fallback), so no descendant ever outlives its owner.
Process runner (Command) — async (tokio) run-and-capture of a child's stdout/stderr and exit status, built on the group layer, with a mockable ProcessRunner seam for tests.

Async throughout. Errors are structured (Error); a non-zero exit is reported in the result, not raised, until you call ProcessResult::ensure_success.

Status: feature-complete — process groups, the runner and capture helpers, streaming, interactive stdin, push line-handlers, output-buffer policies, encoding overrides, line counters, and CPU/memory stats. See CHANGELOG.md.

Install

cargo add processkit

This crate requires a tokio runtime.

Usage

use processkit::{Command, ProcessGroup, Stdin};

#[tokio::main]
async fn main() -> processkit::Result<()> {
    // Capture output; a non-zero exit does not error on its own.
    let result = Command::new("git").args(["rev-parse", "HEAD"]).output_string().await?;
    println!("HEAD is {}", result.stdout().trim());

    // Require success and get trimmed stdout directly.
    let version = Command::new("cargo").arg("--version").run().await?;
    println!("{version}");

    // Feed stdin.
    let sorted = Command::new("sort")
        .stdin(Stdin::from_string("banana\napple\n"))
        .output_string()
        .await?;
    println!("{}", sorted.stdout());

    // Share one kill-on-drop group across several children; dropping the group
    // reaps the whole tree.
    let group = ProcessGroup::new()?;
    let _server = group.start(&Command::new("some-server")).await?;
    // ... work ...
    group.shutdown().await?; // graceful SIGTERM → wait → SIGKILL (Unix); atomic on Windows

    Ok(())
}

Wrapping a CLI tool

CliClient + the cli_client! macro turn a typed wrapper around an external tool (git, jj, gh, …) into just its parsers — the runner is injectable, so the wrapper is hermetically testable with a ScriptedRunner (no subprocess):

use processkit::{cli_client, ProcessRunner, Result};
use std::path::Path;

cli_client!(pub struct Git => "git");

impl<R: ProcessRunner> Git<R> {
    async fn head(&self, dir: &Path) -> Result<String> {
        self.core.text(self.core.command_in(dir, ["rev-parse", "HEAD"])).await
    }
}

Testing

cargo test                 # hermetic unit tests (no subprocess)
cargo test -- --ignored    # real-subprocess + kill-on-drop tests
cargo test --features mock  # the generated MockRunner

License