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
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
//! Stops every live child group when the tool itself receives SIGINT,
//! SIGTERM or SIGHUP, runs the tool's clean-ups, and then takes the
//! signal's default action. It exists on Unix with the `forward` feature.
//!
//! [`install`] starts one thread for the life of the process. When a
//! signal arrives, the thread:
//!
//! 1. takes the registry's lock and holds it until the process ends, so no
//! new child starts;
//! 2. sends the received signal, then SIGCONT, to every listed group, and
//! to a listed child that moved to another group;
//! 3. waits up to [`FORWARD_GRACE`] until every listed child has exited;
//! 4. sends SIGKILL to every listed group;
//! 5. runs each clean-up that [`clean_up`] registered;
//! 6. takes the signal's default action, which ends the tool as the signal
//! would have.
//!
//! A run lists its child while it holds the registry's lock around the
//! start, when the child leads a group of its own
//! ([`Scope::Group`](crate::Scope::Group)). The run unlists it under the
//! same lock before it reaps it, so the forwarder never signals a process
//! id that another process may have taken.
//!
//! The forwarder must be the only handler that ends the tool on SIGINT,
//! SIGTERM or SIGHUP. A tool that keeps crumbkit-usage's log beside the
//! forwarder starts it with `start_under(forward::clean_up)`, so the log
//! starts no signal thread. The line is the first clean-up only when
//! `start_under` runs before anything else registers one. Plain
//! `start` beside [`install`] leaves two handlers that each end the tool,
//! and neither crate can detect that (ADR-0179).
//!
//! A tool that hands the terminal to a child with crumbkit-child calls
//! [`handed_over`] just before the hand-over, so Ctrl-C ends only the child.
//!
//! ```no_run
//! fn remove_lock_file() {}
//!
//! crumbkit_process::forward::clean_up(remove_lock_file);
//! crumbkit_process::forward::install()?;
//! # Ok::<(), std::io::Error>(())
//! ```
use io;
use Child;
use ;
use ;
use Builder;
use ;
use ;
use ;
use Signals;
use cratesys;
/// How long the forwarder waits for the listed children to exit after it
/// sends them the tool's signal, before it sends SIGKILL.
pub const FORWARD_GRACE: Duration = from_secs;
/// How long the forwarder sleeps between checks on the listed children.
const CHECK: Duration = from_millis;
/// The live children that lead a group of their own, by process id.
static LISTED: = new;
/// The functions that the forwarder runs before the tool ends.
static CLEAN_UPS: = new;
/// Whether a child has taken the terminal, which [`handed_over`] records.
static HANDED_OVER: AtomicBool = new;
/// Whether the forwarder's thread started, which [`install`] decides once.
static INSTALLED: = new;
/// Starts the thread that forwards SIGINT, SIGTERM and SIGHUP to every
/// live child group. A second call does nothing and returns the result of
/// the first.
///
/// The thread stays for the life of the process, because removing a
/// signal-hook handler does not restore the signal's default action. The
/// handler replaces an inherited disposition that ignores SIGINT or SIGHUP,
/// as `nohup` sets, because no safe API reads that disposition.
///
/// # Errors
///
/// Returns the operating system's error kind when the handlers cannot be
/// installed or the thread cannot start.
/// Registers `clean_up` to run when the forwarder has stopped the listed
/// groups and before the tool ends. The clean-ups run in the order that
/// they were registered, each function is kept once, and a clean-up that
/// panics does not stop the others. A clean-up that never returns stops the
/// later ones, so a tool that must write crumbkit-usage's line calls
/// `start_under(forward::clean_up)` before it registers anything else.
///
/// A clean-up must not start a run with
/// [`Scope::Group`](crate::Scope::Group), or wait for a thread that runs
/// one. The forwarder holds the list's lock while the clean-ups run, and
/// such a run waits for that lock forever, so the tool never ends. A run
/// with [`Scope::Child`](crate::Scope::Child) takes no lock.
/// Tells the forwarder that a child is about to take the terminal. From now
/// until the tool ends, the forwarder drops SIGINT, as crumbkit-child ignores
/// it on Unix (ADR-0042, ADR-0179), so Ctrl-C reaches only the child.
/// SIGTERM and SIGHUP still reach the listed groups as before. The child
/// that takes the terminal is not on the forwarder's list, so a SIGTERM or
/// SIGHUP sent to the tool during a hand-over ends the tool and leaves that
/// child on the terminal.
///
/// A tool that hands over the terminal beside the forwarder calls this just
/// before `crumbkit_child::hand_over`.
/// Installs the handlers and starts the forwarder's thread.
/// Stops every listed group on the signal `raw`, runs the clean-ups, and
/// ends the tool as `raw` would have.
/// Sends `signal` to each group of `listed`. A refusal is skipped, because
/// the SIGKILL that follows still applies.
/// Starts a child with `spawn` while it holds the registry's lock, and
/// lists the child when it starts.
pub
/// Unlists the child `pid` and reaps it with `reap`, both under the
/// registry's lock.
pub
/// Returns the locked list. Each change is a single push or retain, so a
/// panic while the lock was held cannot leave it half changed.