signal_mod/
lib.rs

1//! Unified OS signal handling for Rust.
2//!
3//! `signal-mod` is a runtime-agnostic substrate for cross-platform
4//! signal handling and graceful shutdown orchestration. It provides:
5//!
6//! - A platform-neutral [`Signal`] enum covering SIGTERM, SIGINT,
7//!   SIGHUP, SIGQUIT, SIGPIPE, SIGUSR1, SIGUSR2 and their Windows
8//!   console-event equivalents.
9//! - A [`Coordinator`] that owns the shutdown state machine and runs
10//!   priority-ordered [`ShutdownHook`]s under a configurable timeout
11//!   ladder.
12//! - Cloneable [`ShutdownToken`] (observer) and [`ShutdownTrigger`]
13//!   (initiator) handles that can be passed independently through a
14//!   program's supervision tree.
15//! - Optional runtime adapters for `tokio` and `async-std` exposing
16//!   `token.wait().await`.
17//!
18//! # Quick start
19//!
20//! ```no_run
21//! use signal_mod::{Coordinator, ShutdownReason, SignalSet};
22//! use std::time::Duration;
23//!
24//! # #[cfg(feature = "tokio")]
25//! #[tokio::main]
26//! async fn main() -> signal_mod::Result<()> {
27//!     let coord = Coordinator::builder()
28//!         .signals(SignalSet::graceful())
29//!         .graceful_timeout(Duration::from_secs(5))
30//!         .hook(signal_mod::hook_from_fn(
31//!             "flush-logs",
32//!             100,
33//!             |reason| eprintln!("shutting down: {reason}"),
34//!         ))
35//!         .build();
36//!
37//!     coord.install()?;
38//!
39//!     let token = coord.token();
40//!     token.wait().await;
41//!
42//!     let reason = token.reason().unwrap_or(ShutdownReason::Requested);
43//!     coord.run_hooks(reason);
44//!     Ok(())
45//! }
46//! # #[cfg(not(feature = "tokio"))]
47//! # fn main() {}
48//! ```
49//!
50//! See `.dev/DESIGN.md` and `REPS.md` for the design contract.
51
52#![doc(html_root_url = "https://docs.rs/signal-mod")]
53#![cfg_attr(docsrs, feature(doc_cfg))]
54#![forbid(unsafe_code)]
55#![warn(missing_docs)]
56
57mod coord;
58mod error;
59mod hook;
60mod install;
61mod reason;
62mod signal;
63mod state;
64mod token;
65
66pub use crate::coord::{Coordinator, CoordinatorBuilder, Statistics};
67pub use crate::error::{Error, Result};
68pub use crate::hook::{hook_from_fn, FnHook, ShutdownHook};
69pub use crate::reason::ShutdownReason;
70pub use crate::signal::{Signal, SignalSet, SignalSetIter};
71pub use crate::token::{ShutdownToken, ShutdownTrigger};
72
73/// Crate version string, populated by Cargo at build time.
74pub const VERSION: &str = env!("CARGO_PKG_VERSION");
signal_mod/lib.rs

signal_mod/
lib.rs
