Skip to main content

Crate sysprims_timeout

Crate sysprims_timeout 

Source
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

When a command times out, the acquired process group or Windows Job Object 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);
    }
}

Re-exports§

pub use managed::close as containment_close;
pub use managed::identity as containment_identity;
pub use managed::poll as containment_poll;
pub use managed::spawn as containment_spawn;
pub use managed::terminate as containment_terminate;
pub use managed::wait as containment_wait;
pub use managed::ManagedSnapshot;
pub use managed::ManagedSpawnRequest;

Modules§

managed
Native-owned managed containment lifecycle for language bindings.

Structs§

ContainmentAdoptionError
Error returned when containment cannot be acquired.
ContainmentGuard
An owned, stateful containment capability and child lifecycle.
ContainmentIdentity
Stable process evidence captured when containment is acquired.
ContainmentOutcome
Result from terminating an owned containment guard.
SpawnInGroupConfig
Configuration for spawn_in_group.
SpawnInGroupResult
TerminateTreeConfig
Configuration for PID-based terminate-tree.
TerminateTreeResult
TimeoutConfig
Configuration for timeout execution.

Enums§

ContainmentBoundaryStrength
Strength of the acquired containment boundary.
ContainmentCompletionEvidence
Point-in-time evidence observed after the final containment cleanup action.
ContainmentObservation
Read-only mechanism used to observe containment membership.
ContainmentSpawnError
Error returned when an owned contained spawn cannot complete.
GroupingMode
Process grouping strategy.
TimeoutOutcome
Outcome of timeout execution.
TreeKillReliability
Reliability of tree-kill operation.

Constants§

SIGKILL
SIGKILL signal number (9)
SIGTERM
SIGTERM signal number (15)

Traits§

ContainmentChild
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.