simple-sigh 0.1.0

Simple signal handler, intended for examples.
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
75
76
77

#![allow(clippy::needless_doctest_main)]
//! A simple signal handler.
//!
//! On unix, register `SIGINT`/`SIGTERM` signal handlers that call a closure to
//! process the signals.  On Windows, register "console control" handlers to
//! call a closure on Ctrl+C, Ctrl+Break and close events.
//!
//! The closure is called once and it is assumed that it will cause the
//! application to terminate.
//!
//! # Usage
//! The application must call [`init()`] early (before setting up any other
//! signal handlers or spawning threads).  After `init()` has been called, it
//! must call [`register()`] to set the callback closure that will be called
//! when one of the signals of interest is raised.
//!
//! ## Waiting for termination requests
//! Applications that are run on spawned threads can use signaling mechanisms
//! like a `Condvar` or a channel to signal from the signal handler to `main()`
//! that the application should be terminated.  However, because it is assumed
//! that this is a somewhat common use-case for `simple-sigh` it provides a
//! pre-baked solution for this pattern: `init()` returns a [`KillWait`] object
//! that has a [`KillWait::wait()`] method that will block indefinitely and
//! wait for the signal handler to trigger.
//!
//! ```no_run
//! fn main() {
//!   let kw = simple_sigh::init().unwrap();
//!
//!   // .. spawen application thread here ..
//!
//!   // Set a signal handler callback
//!   simple_sigh::register(move |_| {
//!     println!("Received signal");
//!     // .. signal application runtime to terminate here ..
//!   })
//!   .unwrap();
//!
//!   // Wait for some kind of abortion signal to be received
//!   println!("Wait for interrupt/termination signal..");
//!   kw.wait();
//!   println!("Bye!");
//! }
//! ```
//!
//! ## Known limitations
//! `simple-sigh` isn't intended for production; it was originally designed for
//! use in examples, and it may be lossy with regards to error handling.
//! The general rule is that `simple-sigh` belongs in `dev-dependencies` rather
//! than `dependencies`.

mod err;

#[cfg(unix)]
mod unix;

#[cfg(windows)]
mod win;

pub use err::Error;

#[cfg(unix)]
pub use unix::{init, register, KillWait};

#[cfg(windows)]
pub use win::{init, register, KillWait};

/// Signal type that caused the signal handler to run.
pub enum SigType {
  /// `SIGINT` on unixy systems.  Ctrl+C on Windows.
  Int,

  /// `SIGTERM` on unixy systems.  Ctrl+Break or console close on Windows.
  Term
}

// vim: set ft=rust et sw=2 ts=2 sts=2 cinoptions=2 tw=79 :