Skip to main content

runnerd_core/scheduler/
waits.rs

1//! How long each pool's next job has waited for memory or CPU, and whether a barrier has served the pool (ADR 0096, 0098,
2//! 0115). `Waits` is one value that only its own methods here write, in the engine and in a replay alike; what the waits
3//! decide is in `priority`.
4
5use std::time::{Duration, SystemTime};
6
7use super::priority::{PRIORITY_AFTER, SERVED_PRIORITY_AFTER, Scarce};
8
9/// Since when a job has waited for something scarce.
10#[derive(Debug, Clone, Copy, PartialEq, Eq)]
11pub struct Wait {
12    /// The job's ID: a wait counts for this job alone, so it cannot outlive it.
13    pub job: u64,
14    /// When a scheduling plan first held it.
15    pub since: SystemTime,
16}
17
18/// What a pool's next job has waited for, and whether a barrier has served the pool. Each clock runs from the first plan
19/// that held the job for it and goes on through a plan that holds it for the other, or for a slot; the two are separate
20/// because a pool's next job for memory and its next job for CPU can be different jobs.
21///
22/// Only these methods write it, here or in a replay (ADR 0115). Nothing of it survives a restart; a reload keeps the
23/// waits of the pools still configured.
24#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
25pub struct Waits {
26    /// Its wait for memory.
27    memory: Option<Wait>,
28    /// Its wait for CPU.
29    cpu: Option<Wait>,
30    /// The waiting job, if a plan's barrier was ever its own. Not only the last plan's: the plan that starts it has no
31    /// barrier, as it fits, and a start refused, or that failed preparing its caches, plans again. A failure that brings
32    /// a backoff clears this with the waits.
33    owner: Option<u64>,
34    /// Whether a runner of the pool started for a job that owned a barrier, since its queue last emptied: its next jobs
35    /// wait `SERVED_PRIORITY_AFTER`.
36    served: bool,
37    /// Whether the last plan held the pool's next job for CPU, as the status says. A start or a listing between two
38    /// plans leaves it: only the next plan says otherwise.
39    cpu_held: bool,
40}
41
42impl Waits {
43    /// Whether nothing is kept for the pool.
44    pub fn is_empty(&self) -> bool {
45        *self == Waits::default()
46    }
47
48    /// Starts the clock of `scarce` for `job`, unless one runs; whether it started.
49    pub fn note(&mut self, scarce: Scarce, job: u64, now: SystemTime) -> bool {
50        let wait = match scarce {
51            Scarce::Memory => &mut self.memory,
52            Scarce::Cpu => &mut self.cpu,
53        };
54        let started = wait.is_none();
55        wait.get_or_insert(Wait { job, since: now });
56        started
57    }
58
59    /// Drops what is kept for the jobs `queued` says are gone. The mark stays: a job taken elsewhere says nothing of the
60    /// jobs behind it.
61    pub fn retain(&mut self, queued: impl Fn(u64) -> bool) {
62        for wait in [&mut self.memory, &mut self.cpu] {
63            if wait.is_some_and(|wait| !queued(wait.job)) {
64                *wait = None;
65            }
66        }
67        self.owner = self.owner.filter(|job| queued(*job));
68    }
69
70    /// Notes that the plan's barrier is `job`'s, if this pool waits for it.
71    pub fn own(&mut self, job: u64) {
72        let waits = [self.memory, self.cpu];
73        if waits.iter().flatten().any(|wait| wait.job == job) {
74            self.owner = Some(job);
75        }
76    }
77
78    /// A runner of the pool is in its slot: its waits end, and if it came to a job that owned a barrier, the barrier has
79    /// served the pool; whether this start is the one that served it. A proposed start, a deferred one or one that
80    /// failed comes to nothing, so it does not count.
81    pub fn started(&mut self) -> bool {
82        let served = self.served || self.owner.is_some();
83        let newly = served && !self.served;
84        *self = Waits {
85            served,
86            cpu_held: self.cpu_held,
87            ..Waits::default()
88        };
89        newly
90    }
91
92    /// The pool may no longer start a runner: nothing is kept for it.
93    pub fn stopped(&mut self) {
94        *self = Waits::default();
95    }
96
97    /// Says whether the plan just made held the pool's next job for CPU.
98    pub fn set_cpu_held(&mut self, held: bool) {
99        self.cpu_held = held;
100    }
101
102    /// Whether the last plan held the pool's next job for CPU.
103    pub fn cpu_held(&self) -> bool {
104        self.cpu_held
105    }
106
107    /// Its wait for CPU, if any.
108    pub fn cpu(&self) -> Option<Wait> {
109        self.cpu
110    }
111
112    /// A listing that succeeded shows none of the pool's jobs queued: the next job to wait is a new contention.
113    pub fn emptied(&mut self) {
114        self.served = false;
115    }
116
117    /// How long a job of the pool waits before it may own a barrier.
118    fn limit(&self) -> Duration {
119        if self.served {
120            SERVED_PRIORITY_AFTER
121        } else {
122            PRIORITY_AFTER
123        }
124    }
125
126    /// When each wait reaches its limit, for a replay to look again then.
127    pub fn deadlines(&self) -> impl Iterator<Item = SystemTime> {
128        let limit = self.limit();
129        [self.memory, self.cpu]
130            .into_iter()
131            .flatten()
132            .map(move |wait| wait.since + limit)
133    }
134
135    /// When `job` first had waited long enough for either, if it has by `now`: a job that waited for CPU and now lacks
136    /// memory, or the other way round, keeps what it waited.
137    pub(super) fn matured(&self, job: u64, now: SystemTime) -> Option<SystemTime> {
138        let limit = self.limit();
139        [self.memory, self.cpu]
140            .into_iter()
141            .flatten()
142            .filter(|wait| wait.job == job)
143            .map(|wait| wait.since + limit)
144            .filter(|reached| *reached <= now)
145            .min()
146    }
147}
148
149#[cfg(test)]
150impl Waits {
151    /// With a wait for memory, for tests that start from one.
152    pub(crate) fn with_memory(mut self, wait: impl Into<Option<Wait>>) -> Self {
153        self.memory = wait.into();
154        self
155    }
156
157    /// With a wait for CPU, for tests that start from one.
158    pub(crate) fn with_cpu(mut self, wait: impl Into<Option<Wait>>) -> Self {
159        self.cpu = wait.into();
160        self
161    }
162
163    /// With a barrier having served the pool, or not.
164    pub(crate) fn with_served(mut self, served: bool) -> Self {
165        self.served = served;
166        self
167    }
168
169    /// Its wait for memory, for tests to read.
170    pub(crate) fn memory(&self) -> Option<Wait> {
171        self.memory
172    }
173
174    /// The job that owned a barrier, for tests to read.
175    pub(crate) fn owner(&self) -> Option<u64> {
176        self.owner
177    }
178
179    /// Whether a barrier has served the pool, for tests to read.
180    pub(crate) fn served(&self) -> bool {
181        self.served
182    }
183
184    /// Its wait for memory, for tests that age it.
185    pub(crate) fn memory_mut(&mut self) -> Option<&mut Wait> {
186        self.memory.as_mut()
187    }
188
189    /// Its wait for CPU, for tests that age it.
190    pub(crate) fn cpu_mut(&mut self) -> Option<&mut Wait> {
191        self.cpu.as_mut()
192    }
193}