signal-mod 1.0.0

Cross-platform OS signal handling and graceful-shutdown orchestration for Rust. One API for SIGTERM, SIGINT, SIGHUP, SIGQUIT, SIGPIPE, SIGUSR1, SIGUSR2 and the Windows console control events, with cloneable observer and initiator handles, priority-ordered shutdown hooks, and optional adapters for the Tokio and async-std runtimes.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74

//! Unified OS signal handling for Rust.
//!
//! `signal-mod` is a runtime-agnostic substrate for cross-platform
//! signal handling and graceful shutdown orchestration. It provides:
//!
//! - A platform-neutral [`Signal`] enum covering SIGTERM, SIGINT,
//!   SIGHUP, SIGQUIT, SIGPIPE, SIGUSR1, SIGUSR2 and their Windows
//!   console-event equivalents.
//! - A [`Coordinator`] that owns the shutdown state machine and runs
//!   priority-ordered [`ShutdownHook`]s under a configurable timeout
//!   ladder.
//! - Cloneable [`ShutdownToken`] (observer) and [`ShutdownTrigger`]
//!   (initiator) handles that can be passed independently through a
//!   program's supervision tree.
//! - Optional runtime adapters for `tokio` and `async-std` exposing
//!   `token.wait().await`.
//!
//! # Quick start
//!
//! ```no_run
//! use signal_mod::{Coordinator, ShutdownReason, SignalSet};
//! use std::time::Duration;
//!
//! # #[cfg(feature = "tokio")]
//! #[tokio::main]
//! async fn main() -> signal_mod::Result<()> {
//!     let coord = Coordinator::builder()
//!         .signals(SignalSet::graceful())
//!         .graceful_timeout(Duration::from_secs(5))
//!         .hook(signal_mod::hook_from_fn(
//!             "flush-logs",
//!             100,
//!             |reason| eprintln!("shutting down: {reason}"),
//!         ))
//!         .build();
//!
//!     coord.install()?;
//!
//!     let token = coord.token();
//!     token.wait().await;
//!
//!     let reason = token.reason().unwrap_or(ShutdownReason::Requested);
//!     coord.run_hooks(reason);
//!     Ok(())
//! }
//! # #[cfg(not(feature = "tokio"))]
//! # fn main() {}
//! ```
//!
//! See `.dev/DESIGN.md` and `REPS.md` for the design contract.

#![doc(html_root_url = "https://docs.rs/signal-mod")]
#![cfg_attr(docsrs, feature(doc_cfg))]
#![forbid(unsafe_code)]
#![warn(missing_docs)]

mod coord;
mod error;
mod hook;
mod install;
mod reason;
mod signal;
mod state;
mod token;

pub use crate::coord::{Coordinator, CoordinatorBuilder, Statistics};
pub use crate::error::{Error, Result};
pub use crate::hook::{hook_from_fn, FnHook, ShutdownHook};
pub use crate::reason::ShutdownReason;
pub use crate::signal::{Signal, SignalSet, SignalSetIter};
pub use crate::token::{ShutdownToken, ShutdownTrigger};

/// Crate version string, populated by Cargo at build time.
pub const VERSION: &str = env!("CARGO_PKG_VERSION");