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}