Expand description
sysprims-timeout: Process timeout with group-by-default tree management.
This crate provides:
- Process execution with timeout (
run_with_timeout) - Group-by-default semantics (cooperative process groups signaled on timeout)
- Signal escalation (SIGTERM → SIGKILL after configurable delay)
- Observable fallback status for tree-kill reliability
§Group-by-Default
The core differentiator of sysprims over GNU timeout. When a command times out, the acquired process group is signaled, not just the direct child:
- Unix: Creates a new process group; child is group leader
- Windows: Creates a Job Object with
KILL_ON_JOB_CLOSE
This gives race-free group acquisition and signaling eligibility. It is not an OS-enforced promise that descendants cannot later leave the group.
§Examples
use std::time::Duration;
use sysprims_timeout::{run_with_timeout, TimeoutConfig, TimeoutOutcome};
let result = run_with_timeout(
"sleep",
&["60"],
Duration::from_secs(5),
TimeoutConfig::default(),
).unwrap();
match result {
TimeoutOutcome::Completed { exit_status } => {
println!("Command completed: {:?}", exit_status);
}
TimeoutOutcome::TimedOut { signal_sent, escalated, .. } => {
println!("Timed out, sent signal {}, escalated: {}", signal_sent, escalated);
}
}Structs§
- Containment
Adoption Error - Error returned when containment cannot be acquired.
- Containment
Guard - An owned, stateful containment capability and child lifecycle.
- Containment
Identity - Stable process evidence captured when containment is acquired.
- Containment
Outcome - Result from terminating an owned containment guard.
- Spawn
InGroup Config - Configuration for
spawn_in_group. - Spawn
InGroup Result - Terminate
Tree Config - Configuration for PID-based terminate-tree.
- Terminate
Tree Result - Timeout
Config - Configuration for timeout execution.
Enums§
- Containment
Boundary Strength - Strength of the acquired containment boundary.
- Containment
Completion Evidence - Point-in-time evidence observed after the final containment cleanup action.
- Containment
Observation - Read-only mechanism used to observe containment membership.
- Containment
Spawn Error - Error returned when an owned contained spawn cannot complete.
- Grouping
Mode - Process grouping strategy.
- Timeout
Outcome - Outcome of timeout execution.
- Tree
Kill Reliability - Reliability of tree-kill operation.
Constants§
Traits§
- Containment
Child - Minimal owned-child contract used by
ContainmentGuard.
Functions§
- adopt_
contained - Adopt an already-running child into an owned containment guard.
- contain_
acquired_ ⚠session - Consume a sealed same-spawn session receipt with its owned child.
- run_
with_ timeout - Run a command with timeout.
- run_
with_ timeout_ default - Run a command with timeout using default configuration.
- spawn_
contained - Spawn a standard-library child and return its owned containment guard.
- spawn_
in_ group - Spawn a process in a new process group on Unix.
- terminate_
tree - Terminate a process by PID with escalation.