runnerd_core/api/queue.rs
1//! What holds the queue as a whole, for a script to ask in one call: whether a queued job waits for the host's
2//! memory; and what a job's wait is counted under in the history, [`WaitCause`] (ADR 0154). It reads the status the
3//! daemon served; it decides nothing about scheduling.
4
5use serde::{Deserialize, Serialize};
6
7use super::{QueueShown, QueuedJob, RepositoryStatus, Status, Waiting};
8
9/// What a queued job's wait is counted under in the history, one per [`Waiting`] reason or a few of them together
10/// (ADR 0154): each plan that holds a job adds the time to the next plan to its cause. Stored by [`WaitCause::word`],
11/// so a cause a later runnerd adds reads as [`WaitCause::Other`].
12#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
13#[serde(rename_all = "kebab-case")]
14pub enum WaitCause {
15 /// Behind an older job that waited long enough for memory or CPU that no younger one starts before it
16 /// (`Waiting::BehindMemory`, `Waiting::BehindCpu`).
17 Barrier,
18 /// Behind an older job's runner starting first (`Waiting::BehindStart`).
19 Start,
20 /// Every slot of its profile held a runner (`Waiting::NoSlot`).
21 Slot,
22 /// Its runner did not fit the slice's memory budget (`Waiting::Memory`).
23 Budget,
24 /// Its runner did not fit what the host's memory has to spare (`Waiting::HostMemory`).
25 Host,
26 /// Its runner did not fit the CPU budget (`Waiting::Cpu`).
27 Cpu,
28 /// A runner was up or starting for it, waiting for GitHub to hand it a job (`Waiting::RunnerStarting`).
29 Booting,
30 /// Its profile rebuilt its snapshot, pulled its image, or emptied what a host crash may have torn
31 /// (`Waiting::Reseeding`, `Waiting::PullingImage`, `Waiting::Torn`).
32 Preparing,
33 /// Its repository was paused (`Waiting::Paused`).
34 Paused,
35 /// Runners of its repository failed, so none started for a while (`Waiting::Backoff`).
36 Backoff,
37 /// No pool served its labels (`Waiting::NoPool`).
38 NoPool,
39 /// A reason this build does not know: a `Waiting` from a newer daemon, or a cause a later runnerd stored.
40 #[serde(other)]
41 Other,
42}
43
44impl WaitCause {
45 /// Every cause, in the order a split lists them when two took as long.
46 pub const ALL: [WaitCause; 12] = [
47 WaitCause::Barrier,
48 WaitCause::Start,
49 WaitCause::Slot,
50 WaitCause::Budget,
51 WaitCause::Host,
52 WaitCause::Cpu,
53 WaitCause::Booting,
54 WaitCause::Preparing,
55 WaitCause::Paused,
56 WaitCause::Backoff,
57 WaitCause::NoPool,
58 WaitCause::Other,
59 ];
60
61 /// Its name as one word, the history's key and the API's: `barrier`, `start`, `slot`, `budget`, `host`, `cpu`,
62 /// `booting`, `preparing`, `paused`, `backoff`, `no-pool` or `other`.
63 pub fn word(self) -> &'static str {
64 match self {
65 WaitCause::Barrier => "barrier",
66 WaitCause::Start => "start",
67 WaitCause::Slot => "slot",
68 WaitCause::Budget => "budget",
69 WaitCause::Host => "host",
70 WaitCause::Cpu => "cpu",
71 WaitCause::Booting => "booting",
72 WaitCause::Preparing => "preparing",
73 WaitCause::Paused => "paused",
74 WaitCause::Backoff => "backoff",
75 WaitCause::NoPool => "no-pool",
76 WaitCause::Other => "other",
77 }
78 }
79
80 /// The cause `word` names; [`WaitCause::Other`] for a word this build does not know.
81 pub fn from_word(word: &str) -> WaitCause {
82 WaitCause::ALL
83 .into_iter()
84 .find(|cause| cause.word() == word)
85 .unwrap_or(WaitCause::Other)
86 }
87
88 /// What it is, as a label: `Behind a barrier`, `Host memory`.
89 pub fn label(self) -> &'static str {
90 match self {
91 WaitCause::Barrier => "Behind a barrier",
92 WaitCause::Start => "Behind an older job's start",
93 WaitCause::Slot => "No free slot",
94 WaitCause::Budget => "Memory budget",
95 WaitCause::Host => "Host memory",
96 WaitCause::Cpu => "CPU budget",
97 WaitCause::Booting => "Runner starting",
98 WaitCause::Preparing => "Snapshot, image or cleanup",
99 WaitCause::Paused => "Repository paused",
100 WaitCause::Backoff => "Runners failing",
101 WaitCause::NoPool => "No profile serves it",
102 WaitCause::Other => "Another reason",
103 }
104 }
105}
106
107impl Waiting {
108 /// What a wait for it is counted under in the history.
109 pub fn cause(&self) -> WaitCause {
110 match self {
111 Waiting::BehindMemory { .. } | Waiting::BehindCpu { .. } => WaitCause::Barrier,
112 Waiting::BehindStart { .. } => WaitCause::Start,
113 Waiting::NoSlot { .. } => WaitCause::Slot,
114 Waiting::Memory { .. } => WaitCause::Budget,
115 Waiting::HostMemory { .. } => WaitCause::Host,
116 Waiting::Cpu { .. } => WaitCause::Cpu,
117 Waiting::RunnerStarting => WaitCause::Booting,
118 Waiting::Reseeding { .. } | Waiting::PullingImage { .. } | Waiting::Torn { .. } => {
119 WaitCause::Preparing
120 }
121 Waiting::Paused => WaitCause::Paused,
122 Waiting::Backoff { .. } => WaitCause::Backoff,
123 Waiting::NoPool { .. } => WaitCause::NoPool,
124 Waiting::Unknown => WaitCause::Other,
125 }
126 }
127}
128
129impl QueuedJob {
130 /// Whether it waits for the host's memory: it does not fit what the host has to spare beside its other programs
131 /// (`Waiting::HostMemory`), or it waits behind an older job for memory (`Waiting::BehindMemory`) and that job waits
132 /// for the host's memory. Memory the host's other programs give back would let it start. `false` also where
133 /// [`Status::host_wait`] cannot tell: a job not planned yet, one behind a job not in `status`, and a reason this
134 /// client does not know.
135 pub fn waits_for_host_memory(&self, status: &Status) -> bool {
136 self.host_chain(status) == Some(true)
137 }
138
139 /// Whether it waits for the host's memory, or `None` when `status` cannot tell: no reason yet, a reason this
140 /// client does not know, or a wait behind a job `status` does not show.
141 fn host_chain(&self, status: &Status) -> Option<bool> {
142 let mut job = self;
143 // Each step goes to an older job, so a chain ends within the queue; the bound only guards a malformed one.
144 for _ in 0..=status.queued.len() {
145 match job.waiting.as_ref()? {
146 Waiting::HostMemory { .. } => return Some(true),
147 Waiting::Unknown => return None,
148 Waiting::BehindMemory { job: older } => {
149 job = status.queued.iter().find(|queued| queued.id == *older)?;
150 }
151 _ => return Some(false),
152 }
153 }
154 None
155 }
156}
157
158/// Whether queued jobs wait for the host's memory, as [`Status::host_wait`] answers it.
159#[derive(Debug, Clone, Copy, PartialEq, Eq)]
160pub enum HostWait {
161 /// A queued job asked about waits for the host's memory.
162 Waits,
163 /// None does, and the status shows every job asked about with why it waits.
164 Clear,
165 /// The status cannot say that none does: a repository asked about is not listed now, or the daemon that sent it
166 /// does not say whether it is; the daemon is stopping; or a job asked about has no reason this client reads.
167 Unavailable,
168 /// The repository asked about is not one the daemon serves, so the answer would say nothing.
169 UnknownRepository,
170}
171
172impl HostWait {
173 /// Why there is no answer, as a script's error says it; `None` for an answer. `repository` is the one asked about.
174 pub fn trouble(self, repository: Option<&str>) -> Option<String> {
175 match self {
176 HostWait::Waits | HostWait::Clear => None,
177 HostWait::UnknownRepository => Some(format!(
178 "{}: not a repository runnerd serves",
179 repository.unwrap_or_default()
180 )),
181 HostWait::Unavailable => Some(format!(
182 "runnerd cannot say whether {} waits for the host's memory: its queue is not listed now, the daemon \
183 stops, or it is older than this runnerctl",
184 repository.map_or_else(|| "a job".to_owned(), |name| format!("a job of {name}"))
185 )),
186 }
187 }
188}
189
190impl Status {
191 /// Whether a queued job, of `repository` (`owner/name`, in any case, as GitHub reads it) when given, waits for
192 /// the host's memory ([`QueuedJob::waits_for_host_memory`]): what a local build asks before it takes memory CI
193 /// could start with. A job seen waiting is an answer however the rest stands; `Clear` needs every repository
194 /// asked about listed and every job of them read, so a daemon that just started, cannot list, stops, or predates
195 /// [`QueueShown`] is `Unavailable`, never `Clear`.
196 pub fn host_wait(&self, repository: Option<&str>) -> HostWait {
197 let asked: Vec<&RepositoryStatus> = match repository {
198 None => self.repositories.iter().collect(),
199 Some(asked) => match self
200 .repositories
201 .iter()
202 .find(|served| served.name.eq_ignore_ascii_case(asked))
203 {
204 Some(served) => vec![served],
205 None => return HostWait::UnknownRepository,
206 },
207 };
208 let chains: Vec<Option<bool>> = self
209 .queued
210 .iter()
211 .filter(|job| {
212 asked
213 .iter()
214 .any(|served| served.name.eq_ignore_ascii_case(&job.repository))
215 })
216 .map(|job| job.host_chain(self))
217 .collect();
218 if chains.contains(&Some(true)) {
219 HostWait::Waits
220 } else if self.shutting_down
221 || chains.contains(&None)
222 || asked
223 .iter()
224 .any(|served| served.queue != QueueShown::Listed)
225 {
226 HostWait::Unavailable
227 } else {
228 HostWait::Clear
229 }
230 }
231}
232
233#[cfg(test)]
234mod tests;