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
//! 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, `spawn_log_pump`'s `select!` also ending on its
/// `logs` receiver.
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. Cleared where `log_ctl` is not: `tokio_runner`'s writer
/// task parks on `recv()`, so a clone left here past the exit leaks that
/// task and the daemon's half of the socketpair.
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`),
/// which is what [`Self::open_stdin`] filters.
///
/// Cleared with [`Self::to_child`], for that field's reason.
///
/// 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, and
/// the actor would park with it. [`Actor::begin_send_line`] uses
/// `try_send`.
pub(super) to_stdin: Option<mpsc::Sender<StdinWrite>>,
/// 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. A reload replaces
/// `Online` instances, so without this the instance a failed reload left
/// behind would be beyond the reach of the reload that rolls it back. Also
/// read by [`Actor::handle_extra_restart`]'s status guard: an abandoned
/// reload's replacement is armed the same extras an `Online` sheep is
/// (see [`Actor::reload_ready_result`]), so its own liveness probe or
/// memory limit must still be able to restart it.
///
/// Cleared wherever the id gets a new process or a new verdict:
/// [`Actor::respawn`]'s success arm and [`Actor::went_online`].
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).
///
/// `None` on every other status, and not cleared on the way out of
/// `WaitingRestart`. Nothing reads it without the status.
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,
manual: None,
pending_delete: false,
epoch: 0,
ready_tx: None,
actions: ActionWaits::default(),
ready_failed: false,
restart_due: 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())
}
}