signal-mod 1.0.0

Why signal-mod

A long-running Rust service needs three things from the OS-signal layer that the standard library does not provide:

1. A single API across Linux, macOS, and Windows. Today this means picking between ctrlc (cross-platform but limited to Ctrl+C), signal-hook (Unix only, no Windows console-event coverage), or tokio::signal / async-std (runtime-specific, and the two streams have different shapes). signal-mod collapses that choice to one Signal enum and one Coordinator.
2. Cloneable handles for observers and initiators. Subsystems need to know when shutdown happened; admin endpoints, fatal-error sites, and supervisors need to be able to ask for it. Passing the same handle for both is a capability leak; signal-mod splits them into ShutdownToken (observe) and ShutdownTrigger (initiate).
3. Priority-ordered cleanup with a real timeout. Real services need to close listeners before draining workers before flushing caches before releasing pool resources. signal-mod runs hooks in descending priority under a configurable graceful budget, and is panic-safe across hooks (one bad hook does not abort the rest).

What it does

• One API for SIGTERM / SIGINT / SIGHUP / SIGQUIT / SIGPIPE / SIGUSR1 / SIGUSR2 and the Windows console control events (CTRL_C, CTRL_BREAK, CTRL_CLOSE, CTRL_SHUTDOWN).
• Graceful shutdown orchestration with cloneable observer and initiator handles you can pass independently up and down a supervision tree.
• Priority-ordered shutdown hooks with a configurable graceful timeout budget. Hook panics are caught per-hook and do not abort the rest of the sequence.
• Runtime-agnostic substrate with optional adapters for tokio and async-std, plus a synchronous ctrlc-fallback for non-async code.

Install

Add signal-mod to Cargo.toml:

[dependencies]
signal-mod = "1.0"

Default features (std + tokio) are the right choice for a Tokio-driven service. To opt in to a different runtime adapter, disable defaults and pick one feature:

# async-std runtime
signal-mod = { version = "1.0", default-features = false, features = ["std", "async-std"] }

# Synchronous Ctrl+C only, no async runtime
signal-mod = { version = "1.0", default-features = false, features = ["std", "ctrlc-fallback"] }

Features

When both tokio and async-std are enabled, tokio wins (so a workspace that pulls both transitively still gets a single back-end).

Quick start

use std::time::Duration;
use signal_mod::{hook_from_fn, Coordinator, ShutdownReason, SignalSet};

#[tokio::main]
async fn main() -> signal_mod::Result<()> {
    let coord = Coordinator::builder()
        .signals(SignalSet::graceful())
        .graceful_timeout(Duration::from_secs(5))
        .hook(hook_from_fn("close-listener", 1000, |_| {
            // Stop accepting new requests.
        }))
        .hook(hook_from_fn("drain-queues", 500, |_| {
            // Finish in-flight work.
        }))
        .hook(hook_from_fn("flush-logs", 100, |reason| {
            eprintln!("flushing logs: {reason}");
        }))
        .build();

    coord.install()?;

    let token = coord.token();
    token.wait().await;

    let reason = token.reason().unwrap_or(ShutdownReason::Requested);
    let ran = coord.run_hooks(reason);
    eprintln!("ran {ran} shutdown hook(s)");
    Ok(())
}

Examples

Seven runnable examples ship in examples/:

Run any example with:

cargo run --example graceful_shutdown

API at a glance

Full per-item reference with multiple code examples per use case lives in docs/API.md.

signal-mod follows Semantic Versioning. Every item in the public API is covered from 1.0.0 forward; pin to a minor ("1.0") to receive patch fixes automatically.

Performance

Single-platform reference (Windows 11, Rust 1.95.0). Lower is better; rerun cargo bench --bench shutdown_bench to validate on your hardware.

More detail and methodology notes in docs/API.md#performance.

Platform support

* On Windows, the async-std back-end uses a synchronous ctrlc handler for Signal::Interrupt only, because async-std does not ship a native Windows signal stream. The full Windows console event matrix (CTRL_C, CTRL_BREAK, CTRL_CLOSE, CTRL_SHUTDOWN) is available through the tokio back-end.

Testing

signal-mod ships with the following test surface, all run in CI on Linux, macOS, and Windows:

• 21 unit tests in src/.
• 7 integration tests in tests/coordinator_integration.rs.
• 10 property tests (proptest, 256 cases each) in tests/property_tests.rs.
• 20 edge case tests in tests/edge_cases.rs.
• 6 stress tests under concurrent triggers, many observers, and high-volume cloning in tests/stress.rs.
• 6 doctests spanning the crate root, Coordinator, CoordinatorBuilder, Statistics, Coordinator::run_hooks, and hook_from_fn.

Run the full suite:

cargo test --all-features

Run benchmarks:

cargo bench --bench shutdown_bench

MSRV

Rust 1.75. MSRV bumps require a minor version increment per REPS.md section 6.

Contributing

Issues and pull requests are welcome at github.com/jamesgober/signal-mod. Style is enforced via cargo fmt; correctness via cargo clippy --all-targets --all-features -- -D warnings.

License

Licensed under the Apache License, Version 2.0. See LICENSE for the full text.