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
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
//! The Windows counterpart to `sys` (the unix-only module of the same
//! role): a job object per sheep
//!
//! This module exists for one reason — a Win32 job object is what replaces
//! the unix process group — and it is this crate's ONLY unsafe surface on
//! Windows, exactly as `sys.rs` is its only unsafe surface on unix (IR-22,
//! IR-23). Every `unsafe` block below carries its own `// SAFETY:`.
//!
//! # Why a job object, and why it is better than what it replaces
//!
//! `tokio_runner`'s unix arm spawns each sheep with `process_group(0)`, so
//! the sheep leads a group of its own and a negative-pid `SIGKILL` reaches
//! the whole tree. Windows has no process groups in that sense. It has job
//! objects: a kernel container a process is assigned to, which its children
//! inherit automatically, and which can be terminated as a unit.
//!
//! The substitution is close to exact, and in one respect stronger.
//! `kill.rs`'s own module comment records a hole in the unix design — a
//! grandchild that calls `setsid` escapes its group and outlives
//! `kill_tree`. A job has no equivalent hole: a process cannot leave a job
//! it has been assigned to, and a child can only be spawned outside it if
//! the job itself was created with `JOB_OBJECT_LIMIT_BREAKAWAY_OK`, which
//! `Job::create` deliberately does not set. So `kill_tree` on Windows
//! reaches strictly more of the tree than its unix twin does.
//!
//! # What is deliberately NOT set
//!
//! `JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE` would terminate every member the
//! moment the last handle to the job closed — which, since the daemon holds
//! that handle, means the whole flock would die with the shepherd.
//!
//! **That is not shep's behaviour on unix and it is not adopted here.** A
//! sheep whose shepherd is `SIGKILL`ed keeps running, orphaned; the flag
//! would make Windows the one platform where restarting the daemon also
//! stops every app it was supervising. Aligning the two platforms is worth
//! more than the flag's one genuine benefit (no orphan can outlive the
//! daemon and be duplicated by the next one's muster restore), and that
//! hazard is one shep already has, already documents, and should fix the
//! same way on both platforms if it fixes it at all.
//!
//! # Nesting
//!
//! Everything above describes a job shep creates at the top of the tree. It
//! is not always at the top: a CI runner, a container shim or a terminal host
//! may already have put shep itself into a job, and a job created inside
//! another one is a *nested* job with its own rules, since the outer job's
//! limit flags constrain it and Windows before 8 had no nesting at all.
//!
//! This module carried a reporting surface for a while to find out whether
//! that was behind two tests that passed on a developer's Windows box and
//! hung on `windows-latest`. It was not: the cause was a PowerShell test
//! fixture that never ran, and the runner's own outer job turned out to
//! contain a nested job correctly. The surface is gone with the question,
//! and `tests/real_runner_windows.rs` asserts the containment that matters.
// IR-24 exception — the Windows twin of `sys.rs`'s, and
// the only one on this platform. Ten sites, all in this file: eight `unsafe`
// blocks plus the two `unsafe impl`s that make a kernel handle `Send` and
// `Sync`. Of the blocks, seven are FFI calls (`CreateJobObjectW`,
// `SetInformationJobObject`, `AssignProcessToJobObject`, `TerminateJobObject`,
// `CloseHandle`, `GetStdHandle` and `SetHandleInformation`) and one is a
// `mem::zeroed` for a Win32 limit struct. Nothing outside this module writes
// `unsafe` on Windows.
use io;
use RawHandle;
use ;
use ;
use ;
/// Marks this process's own stdio handles non-inheritable.
///
/// **The Windows counterpart to `shep-cli`'s `seal_inherited_fds`, and it is
/// needed for the same reason that one is.** `launch.rs`'s Windows arm used
/// to carry a comment claiming no counterpart was necessary, on the grounds
/// that Windows inherits only handles explicitly marked inheritable. That is
/// true and is not the whole story: `CreateProcess` with `bInheritHandles =
/// TRUE` — which `std` passes whenever any stdio is redirected — inherits
/// **every** inheritable handle the parent holds, not only the ones `std`
/// prepared.
///
/// So a shepherd spawned from a shell that gave `shep` a PIPE for stdout
/// inherits that pipe, and holds it open for its entire life. The daemon
/// never writes to it (its own stdout is redirected to a log file), but the
/// pipe cannot close while a handle to it exists, so the shell blocks
/// forever waiting for output that will never end. Measured: `shep start |
/// Out-Null` hung indefinitely while `shep start` alone returned at once,
/// and `shep flock | Out-Null` — which spawns nothing — was unaffected.
///
/// That is the whole bug, and it is worse than it sounds because piping is
/// the normal case in the place it matters most: a CI job, a
/// `$(shep start ...)`, anything reading shep's output.
///
/// Called immediately before the spawn rather than once at startup: it
/// changes only the INHERIT flag, not the handles themselves, so this
/// process goes on using its own stdio exactly as before — the same
/// narrowness `seal_inherited_fds` has on unix, where it sets `FD_CLOEXEC`
/// and leaves the descriptors open.
///
/// Best-effort by design. A failure here means one spawn may inherit a
/// handle it should not, which is the behaviour that existed before this
/// function; refusing to start a shepherd over it would be the worse
/// outcome, so there is nothing to report and nothing for a caller to do.
/// An anonymous job object owning one sheep and everything it spawns.
///
/// Closed on drop. Dropping does **not** terminate the members — see this
/// module's doc for why `KILL_ON_JOB_CLOSE` is not set.
pub ;
// SAFETY: a job object HANDLE is a kernel handle, not a thread-affine
// resource. Win32 permits any thread to call `AssignProcessToJobObject`,
// `TerminateJobObject` or `CloseHandle` on it, and the handle value is
// plain data. The daemon moves a `Job` into the per-sheep task that owns
// its `RunningProcess`, which is `Send`, so this impl is required and is
// sound for the same reason `std`'s own process handles are `Send`.
unsafe
// SAFETY: as above; every Win32 call this module makes on the handle is
// itself thread-safe, and `Job` exposes no interior mutability.
unsafe