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
//! One registered instance, as the actor holds it.
//!
//! A slot is the actor's whole record of a sheep: its lifecycle entry, the
//! senders reaching its task, and whatever is in flight against it. The
//! actor keeps one per registered id and never awaits process IO while
//! holding it.
use super::*;
/// One registered instance: lifecycle state plus its live senders.
#[derive(Debug)]
pub(super) struct SheepSlot {
/// Lifecycle state (spec, status, restart budget, ...).
pub(super) entry: ProcessEntry,
/// Sender for this sheep's control mailbox; `None` when not running.
pub(super) ctl: Option<mpsc::Sender<SheepCtl>>,
/// A clone of the [`ProcIo::log_ctl`] the most recent successful spawn
/// handed out, which is how a `Reopen` or a `Flush` reaches this sheep's
/// log pump. `None` only for a slot whose spawn never succeeded at all.
///
/// Never cleared, unlike `ctl`: a send fails the moment the pump ends, so
/// clearing this too would be a second copy of that fact. It costs the
/// pump no extra life.
pub(super) log_ctl: Option<mpsc::Sender<LogCtl>>,
/// A clone of the [`ProcIo::to_child`] the most recent successful spawn
/// handed out: the daemon's writing end of this sheep's shepherd channel,
/// and the actor's only way to reach a live child directly. `None`
/// whenever no process is running under this id.
///
/// Not carried as a `ctl` message: [`Actor::claim_manual`] ignores a `Full`
/// on that mailbox on the strength of [`SheepCtl::Kill`] being its sole occupant.
pub(super) to_child: Option<mpsc::Sender<ShepherdMessage>>,
/// Sender for this sheep's signal mailbox, separate from [`Self::ctl`].
/// `None` whenever no process is running under this id.
///
/// A mailbox of its own rather than a [`SheepCtl`] variant: a burst
/// sharing [`Self::ctl`]'s bounded slots would make
/// [`Actor::claim_manual`] drop a stop. Cleared with [`Self::to_child`].
pub(super) signals: Option<mpsc::Sender<SignalRequest>>,
/// A clone of the [`ProcIo::to_stdin`] the most recent successful spawn
/// handed out: the daemon's writing end of this sheep's stdin pipe. `None`
/// whenever no process is running under this id; present but closed when
/// the running one never asked for a pipe (`AppConfig::stdin == false`).
///
/// No `.await` on this sender may appear on the actor loop: an app that has
/// stopped reading fd 0 fills its pipe and blocks the writer task.
pub(super) to_stdin: Option<mpsc::Sender<StdinWrite>>,
/// A clone of the [`ProcIo::pty`] the most recent successful spawn handed
/// out: a hold on this sheep's terminal. `None` whenever no process is
/// running under this id, and for one that runs on pipes.
///
/// Cleared with [`Self::to_stdin`], whose pump it shares.
pub(super) pty: Option<PtyHandle>,
/// Which manual command (if any) is waiting on this sheep's next exit,
/// and who asked for it. Claimed through [`Actor::claim_manual`].
pub(super) manual: Option<PendingManual>,
/// Set whenever a `Delete` targets this id, even if an earlier command
/// already owns `manual`. `manual` records who owns the next Kill; this
/// records intent that must survive that race, so a Delete can never be
/// downgraded to a Stop or a Restart. `handle_exited` checks it on the
/// manual-Restart early return as well as on the `CleanStop` branch.
pub(super) pending_delete: bool,
/// Bumped on every successful respawn. A `RestartDue` timer carries the
/// epoch it was scheduled under, and `handle_restart_due` drops one whose
/// epoch has moved on.
pub(super) epoch: u64,
/// The readiness task's signal sender for the current epoch.
/// `Msg::Ready`'s handler takes it to wake the task.
///
/// `None` means either that no readiness task was ever armed, or that a
/// channel `Ready` already took the sender. A wait that resolved another
/// way leaves its sender here, and a late `Msg::Ready` drops silently.
pub(super) ready_tx: Option<oneshot::Sender<()>>,
/// The action waits armed against this sheep and the replies its app still
/// owes ones that have ended; see [`ActionWaits`].
///
/// Cleared with [`Self::to_child`]: a wait armed against an exited process
/// waits for a reply nobody will write.
pub(super) actions: ActionWaits,
/// This instance's readiness wait ended without a signal, and a reload
/// left it standing anyway: up, registered, and known not to be serving.
///
/// Read by [`Actor::advance_reload`]'s replaceable test, so the instance a
/// failed reload left behind is still within reach of the next one. Also
/// read by [`Actor::handle_extra_restart`]'s status guard: an abandoned
/// reload's replacement is armed the same extras an `Online` sheep is.
pub(super) ready_failed: bool,
/// When this slot's owed respawn falls due, in wall-clock terms.
///
/// The same fact as [`Actor::schedule_restart`]'s monotonic timer, in the
/// only clock that survives an `execve`: a handover carries this and re-arms
/// a fresh timer from it. See
/// [`backoff::adopted_restart_delay`](crate::backoff::adopted_restart_delay).
pub(super) restart_due: Option<SystemTime>,
}
impl SheepSlot {
/// A registered sheep with nothing attached: no mailboxes, no marker, no
/// timer, at epoch zero.
///
/// The base every literal in this module builds from, so a field added
/// here is written once and a caller overwrites only what it owns. Not a
/// `Default`: `entry` has no blank value.
pub(super) fn new(entry: ProcessEntry) -> Self {
Self {
entry,
ctl: None,
log_ctl: None,
to_child: None,
signals: None,
to_stdin: None,
pty: None,
manual: None,
pending_delete: false,
epoch: 0,
ready_tx: None,
actions: ActionWaits::default(),
ready_failed: false,
restart_due: None,
}
}
/// Lands the slot at `status` with nothing left attached to a process
/// that is no longer running.
///
/// [`Self::log_ctl`] is the one handle left in place, for the reason on
/// that field.
pub(super) fn clear_lifecycle(&mut self, status: ProcStatus) {
self.entry.status = status;
self.entry.pid = None;
self.entry.started_at = None;
// Cleared, because nothing exited here: leaving the previous
// process's code would show a sheep that once crashed with 1 as
// still crashing with 1 while it is failing to start at all.
self.entry.last_exit = None;
self.ctl = None;
// `signals`, `to_stdin` and `pty` go wherever `to_child` goes, for the
// reason on each field.
self.to_child = None;
self.signals = None;
self.to_stdin = None;
self.pty = None;
self.ready_tx = None;
}
/// This sheep's shepherd-channel sender while something is still there to
/// receive on it, and `None` when nothing is.
///
/// Read off the channel rather than `AppConfig::channel`, so there is no
/// second copy of the fact. `is_closed` catches an app configured without
/// a channel.
pub(super) fn open_channel(&self) -> Option<&mpsc::Sender<ShepherdMessage>> {
self.to_child
.as_ref()
.filter(|to_child| !to_child.is_closed())
}
/// This sheep's stdin sender while something is still there to receive on
/// it, and `None` when nothing is.
///
/// Read off the channel rather than `AppConfig::stdin`, as
/// [`Self::open_channel`] is. `is_closed` catches an app that never asked
/// for a pipe, whose receiver the runner dropped at spawn.
pub(super) fn open_stdin(&self) -> Option<&mpsc::Sender<StdinWrite>> {
self.to_stdin
.as_ref()
.filter(|to_stdin| !to_stdin.is_closed())
}
/// This sheep's terminal while it is still open, and `None` when it has
/// closed or the sheep has none.
///
/// Read off the handle rather than `AppConfig::pty`, as
/// [`Self::open_stdin`] is.
pub(super) fn open_pty(&self) -> Option<&PtyHandle> {
self.pty.as_ref().filter(|pty| !pty.is_closed())
}
}
#[cfg(test)]
mod tests {
use super::*;
use core::sync::atomic::AtomicBool;
use tokio::sync::broadcast;
use crate::runner::PtyCommand;
use crate::testing::{app_with, plain_entry};
fn slot() -> SheepSlot {
SheepSlot::new(plain_entry(1, app_with("web", |_| {})))
}
/// A handle, and the receiver whose drop closes it.
fn handle() -> (PtyHandle, mpsc::Receiver<PtyCommand>) {
let output = Arc::new(broadcast::channel(1).0);
let (control, commands) = mpsc::channel(1);
let handle = PtyHandle::new(&output, control, Arc::new(AtomicBool::new(false)));
(handle, commands)
}
#[test]
fn open_pty_answers_as_open_stdin_does() {
let mut slot = slot();
assert!(slot.open_pty().is_none(), "a slot with no terminal");
let (handle, commands) = handle();
slot.pty = Some(handle);
assert!(slot.open_pty().is_some(), "a terminal being served");
drop(commands);
assert!(slot.open_pty().is_none(), "a terminal nothing serves");
slot.pty = None;
assert!(slot.open_pty().is_none(), "a cleared slot");
}
}