Crate sigchld

sigchld

This is a low-level utility for child process management. Unix doesn’t provide a portable* API for waiting for a child process to exit with a timeout. The closest thing is waiting for the SIGCHLD signal to be delivered, but Unix signal handling is quite complicated and error-prone. This crate implements SIGCHLD handling (using signal_hook internally for compatibility with other signal handling libraries) and allows any number of threads to wait for that signal, with an optional timeout.

Note that SIGCHLD indicates that any child process has exited, but there’s no (100% reliable) way to know which child it was. You generally need to poll your child process in a loop, and wait again if it hasn’t exited yet. Most applications will want to use a higher-level API that does this loop internally; I’ll list such crates here as they’re implemented.

This crate only supports Unix and doesn’t build on Windows. Portable callers need to put this crate in the [target.'cfg(unix)'.dependencies] section of their Cargo.toml and only use it inside of #[cfg(unix)] blocks or similar.

* Linux supports `signalfd`, but there's no equivalent on e.g. macOS.

Example

let mut waiter = sigchld::Waiter::new()?;
// Any SIGCHLD after this point will be buffered by the Waiter.
let mut child = std::process::Command::new("sleep").arg("1").spawn()?;
// Block until *any* child exits. See also `wait_timeout` and `wait_deadline`.
waiter.wait()?;
// There's only one child process in this example, so we know that it exited. But in general
// we might not know which child woke us up, and then we'd need to wait and check in a loop.
// See the Waiter examples.
assert!(child.try_wait()?.is_some(), "sleep has exited");

Structs

Waiter

An object that buffers SIGCHLD signals so that you can wait on them reliably.