Skip to main content

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;