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
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
//! EXIT SOURCES, ready-made — the one adapter this crate ships, behind the one feature that names a
//! runtime.
//!
//! [`App::halt_on`](crate::App::halt_on) takes a [`conduit::Receiver<()>`](crate::conduit::Receiver)
//! and asks nothing about where it came from, which is what keeps the seat runtime-agnostic: a
//! handler is the application's act, and a library that installed one would be taking a
//! process-wide decision on somebody else's behalf. This module is the exception that proves the
//! rule — an adapter for the runtime a deployment has ALREADY chosen, compiled only where that
//! deployment says so.
//!
//! # The whole module rides `tokio-signal`, and the default graph names no runtime
//!
//! `ingraph` has no `tokio` in its default dependency graph and this changes nothing about that:
//! the feature is off unless a build asks for it, and asking for it is a build that already has a
//! tokio runtime to spawn on. The agnostic law is the crate's, and a named runtime behind a named
//! feature is how a library keeps it while still being usable.
//!
//! # UNIX SIGNALS ride the docs rather than a dependency
//!
//! There is no `sighup()` here, and the absence is deliberate: the shape is four lines an
//! application writes against whatever it already has, and shipping one would be shipping a
//! preference about which signals mean *stop*. Under tokio it is
//! [`tokio::signal::unix`](https://docs.rs/tokio/latest/tokio/signal/unix/):
//!
//! ```ignore
//! use ingraph::conduit;
//! use tokio::signal::unix::{SignalKind, signal};
//!
//! /// A line that speaks the first time this process is sent `SIGTERM`.
//! fn sigterm() -> std::io::Result<conduit::Receiver<()>> {
//! let (fired, source) = conduit::bounded(1);
//! let mut term = signal(SignalKind::terminate())?;
//! tokio::spawn(async move {
//! term.recv().await;
//! let _ = fired.try_send(());
//! });
//! Ok(source)
//! }
//! ```
//!
//! and under any other runtime it is the same four lines with that runtime's own handler in the
//! middle. Register as many as the deployment has —
//! [`halt_on`](crate::App::halt_on) takes each on its own line, and whichever speaks first wakes the
//! park.
use crate;
/// **A LINE THAT SPEAKS WHEN THE PROCESS IS INTERRUPTED** — `Ctrl-C`, or `SIGINT` on unix — ready
/// for [`App::halt_on`](crate::App::halt_on).
///
/// The handler is tokio's ([`tokio::signal::ctrl_c`]) and the line is this crate's, which is the
/// whole of the adapter: what comes back is an ordinary exit source, indistinguishable at the seat
/// from one an application wired itself.
///
/// # It must be called FROM a tokio runtime
///
/// The wait is a task, so this spawns — and [`tokio::spawn`] panics outside a runtime context. A
/// daemon calls it inside its `#[tokio::main]` (or inside `Runtime::block_on` / an
/// `EnterGuard`) and hands the line to the app:
///
/// ```ignore
/// # async fn wire(app: &mut ingraph::App<()>) {
/// app.halt_on(ingraph::signal::ctrl_c());
/// // …and then, on whatever thread is not the executor's:
/// // app.until_stopped();
/// # }
/// ```
///
/// # It fires ONCE, and a handler that could not be installed stays SILENT
///
/// The task ends with the first interrupt, and the line's capacity is one — a second `Ctrl-C`
/// reaches nothing here, which is right: the wind-down is already under way and saying so twice is
/// the same instruction. A deployment that wants the second press to be *abort now* wires that
/// itself, against the same `App`.
///
/// Where tokio REFUSES to install the handler, the line is held open and never speaks. The
/// alternative would be to let the sender go, and a hang-up is news
/// [`halt_on`](crate::App::halt_on) reads as *time to stop* — so a failure to install would become
/// an immediate wind-down nobody asked for. Silence is the honest answer: the deployment stops the
/// way it would have if this source had never been registered.