1use core::time::Duration;
5use std::time::Instant;
6
7use crate::{Error, Percent, Result, origin::Origin};
8
9pub const DEFAULT_WINDOW: Duration = Duration::from_millis(100);
11
12const MIN_WINDOW: Duration = Duration::from_millis(10);
13const MAX_WINDOW: Duration = Duration::from_secs(10);
14
15#[derive(Clone, Copy, Debug, PartialEq, Eq, Default)]
18#[non_exhaustive]
19pub struct Times {
20 pub user: Duration,
22 pub nice: Duration,
24 pub system: Duration,
26 pub idle: Duration,
28 pub iowait: Duration,
30 pub irq: Duration,
32 pub softirq: Duration,
34 pub steal: Duration,
36}
37
38impl Times {
39 fn total(&self) -> Duration {
40 self.busy() + self.idle + self.iowait
41 }
42
43 fn busy(&self) -> Duration {
45 self.user + self.nice + self.system + self.irq + self.softirq + self.steal
46 }
47
48 fn since(&self, earlier: &Times) -> Option<Times> {
51 Some(Times {
52 user: self.user.checked_sub(earlier.user)?,
53 nice: self.nice.checked_sub(earlier.nice)?,
54 system: self.system.checked_sub(earlier.system)?,
55 idle: self.idle.checked_sub(earlier.idle)?,
56 iowait: self.iowait.checked_sub(earlier.iowait)?,
57 irq: self.irq.checked_sub(earlier.irq)?,
58 softirq: self.softirq.checked_sub(earlier.softirq)?,
59 steal: self.steal.checked_sub(earlier.steal)?,
60 })
61 }
62}
63
64#[derive(Clone, Copy, Debug)]
66pub(crate) struct States {
67 pub(crate) iowait: bool,
68 pub(crate) steal: bool,
69 pub(crate) irq: bool,
70}
71
72#[derive(Clone, Copy, Debug)]
78#[non_exhaustive]
79pub struct Usage {
80 pub user: Percent,
82 pub system: Percent,
84 pub idle: Percent,
86 pub iowait: Option<Percent>,
88 pub steal: Option<Percent>,
90 pub irq: Option<Percent>,
92 pub interval: Duration,
94}
95
96impl Usage {
97 #[must_use]
99 pub fn used(&self) -> Percent {
100 self.free().complement()
101 }
102
103 #[must_use]
105 pub fn free(&self) -> Percent {
106 let iowait = self.iowait.map_or(0.0, Percent::value);
107 Percent::from_value(self.idle.value() + iowait)
108 }
109
110 fn from_delta(d: &Times, states: States, interval: Duration) -> Option<Usage> {
113 let total = d.total().as_nanos();
114 if total == 0 {
115 return None;
116 }
117 let share = |part: Duration| Percent::from_ratio_u128(part.as_nanos(), total);
118 Some(Usage {
119 user: share(d.user + d.nice),
120 system: share(d.system),
121 idle: share(d.idle),
122 iowait: states.iowait.then(|| share(d.iowait)),
123 steal: states.steal.then(|| share(d.steal)),
124 irq: states.irq.then(|| share(d.irq + d.softirq)),
125 interval,
126 })
127 }
128}
129
130pub fn times() -> Result<Times> {
138 crate::sys::cpu_times()
139}
140
141pub fn usage() -> Result<Usage> {
154 usage_over(DEFAULT_WINDOW)
155}
156
157pub fn usage_over(window: Duration) -> Result<Usage> {
164 let mut sampler = Sampler::total_only()?;
165 std::thread::sleep(window.clamp(MIN_WINDOW, MAX_WINDOW));
166 sampler.sample()
167}
168
169pub fn used() -> Result<Percent> {
181 usage().map(|u| u.used())
182}
183
184pub fn free() -> Result<Percent> {
191 usage().map(|u| u.free())
192}
193
194#[derive(Debug)]
213pub struct Sampler {
214 total: Times,
216 at: Instant,
217 cores_total: Times,
222 cores: Vec<Times>,
223 scratch: Vec<Times>,
224 cores_at: Instant,
225 origin: Origin,
226}
227
228impl Sampler {
229 pub fn new() -> Result<Sampler> {
235 Self::from(Origin::local())
236 }
237
238 pub(crate) fn from(origin: Origin) -> Result<Sampler> {
240 let total = origin.cpu_times()?;
241 let mut cores = vec![Times::default(); super::logical()];
242 let (cores_total, n) = match read_cores(&origin, &mut cores) {
243 Ok(r) => r,
244 Err(Error::Unsupported { .. }) => (total, 0),
247 Err(e) => return Err(e),
248 };
249 cores.truncate(n);
250 let now = Instant::now();
251 Ok(Sampler {
252 total,
253 at: now,
254 cores_total,
255 scratch: vec![Times::default(); cores.len()],
256 cores,
257 cores_at: now,
258 origin,
259 })
260 }
261
262 fn total_only() -> Result<Sampler> {
264 let now = Instant::now();
265 let total = times()?;
266 Ok(Sampler {
267 total,
268 at: now,
269 cores_total: total,
270 cores: Vec::new(),
271 scratch: Vec::new(),
272 cores_at: now,
273 origin: Origin::local(),
274 })
275 }
276
277 pub fn sample(&mut self) -> Result<Usage> {
285 let now = self.origin.cpu_times()?;
286 let at = Instant::now();
287 let usage = between(&now, &self.total, at.duration_since(self.at));
288 self.total = now;
289 self.at = at;
290 usage
291 }
292
293 pub fn sample_per_core(&mut self) -> Result<(Usage, Vec<Percent>)> {
300 let mut out = vec![Percent::ZERO; self.scratch.len().max(super::logical())];
301 let usage = self.sample_per_core_into(&mut out)?;
302 out.truncate(self.cores.len());
303 Ok((usage, out))
304 }
305
306 pub fn sample_per_core_into(&mut self, out: &mut [Percent]) -> Result<Usage> {
320 let (total, n) = read_cores(&self.origin, &mut self.scratch)?;
321 let at = Instant::now();
322 if out.len() < n {
323 return Err(Error::TooLarge {
324 what: "per-core CPU usage",
325 limit: out.len() as u64,
326 });
327 }
328 let interval = at.duration_since(self.cores_at);
329 let usage = between(&total, &self.cores_total, interval);
330 for (i, now) in self.scratch[..n].iter().enumerate() {
331 out[i] = self
332 .cores
333 .get(i)
334 .and_then(|old| now.since(old))
335 .and_then(|d| Usage::from_delta(&d, crate::sys::CPU_STATES, interval))
336 .map_or(Percent::ZERO, |u| u.used());
337 }
338 self.cores.resize(n, Times::default());
341 self.cores.copy_from_slice(&self.scratch[..n]);
342 self.cores_at = at;
343 self.cores_total = total;
344 usage
345 }
346}
347
348fn between(now: &Times, then: &Times, interval: Duration) -> Result<Usage> {
350 let too_soon = || Error::TooSoon {
351 elapsed: interval,
352 minimum: crate::sys::CPU_TICK,
353 };
354 let delta = now.since(then).ok_or_else(too_soon)?;
355 Usage::from_delta(&delta, crate::sys::CPU_STATES, interval).ok_or_else(too_soon)
356}
357
358const MAX_CORES: usize = 16_384;
363
364fn read_cores(origin: &Origin, buf: &mut Vec<Times>) -> Result<(Times, usize)> {
367 loop {
368 match origin.cpu_times_per_core(buf) {
369 Err(Error::TooLarge { .. }) if buf.len() < MAX_CORES => {
370 let len = (buf.len() * 2 + super::logical()).min(MAX_CORES);
371 buf.resize(len, Times::default());
372 }
373 r => {
374 let (total, n) = r?;
375 return Ok((total, n.min(buf.len())));
376 }
377 }
378 }
379}
380
381#[cfg(test)]
382mod tests {
383 use super::*;
384
385 #[cfg(target_os = "linux")]
386 #[test]
387 fn test_read_cores_grows_for_a_larger_probed_host() {
388 let host = crate::origin::Host {
391 root: crate::linux::fixtures::root("wsl2"),
392 net_dev: "/proc/net/dev",
393 };
394 let origin = Origin::host(std::sync::Arc::new(host));
395 let mut buf = vec![Times::default(); 1];
396 let (_, n) = read_cores(&origin, &mut buf).unwrap();
397 assert_eq!(n, 32);
398 assert!(buf.len() >= 32);
399 }
400
401 const ALL: States = States {
402 iowait: true,
403 steal: true,
404 irq: true,
405 };
406
407 fn ms(n: u64) -> Duration {
408 Duration::from_millis(n)
409 }
410
411 fn times(user: u64, system: u64, idle: u64, iowait: u64, steal: u64) -> Times {
412 Times {
413 user: ms(user),
414 system: ms(system),
415 idle: ms(idle),
416 iowait: ms(iowait),
417 steal: ms(steal),
418 ..Times::default()
419 }
420 }
421
422 #[test]
423 fn test_cpu_usage_steal_busy_iowait_idle() {
424 let d = times(300, 100, 400, 100, 100);
426 let u = Usage::from_delta(&d, ALL, ms(1000)).unwrap();
427 assert_eq!(u.user.to_string(), "30.0%");
428 assert_eq!(u.idle.to_string(), "40.0%");
429 assert_eq!(u.iowait.unwrap().to_string(), "10.0%");
430 assert_eq!(u.steal.unwrap().to_string(), "10.0%");
431 assert_eq!(u.free().to_string(), "50.0%");
432 assert_eq!(u.used().to_string(), "50.0%");
433 }
434
435 #[test]
436 fn test_cpu_usage_states_a_platform_lacks_are_none() {
437 let u = Usage::from_delta(
438 ×(1, 1, 2, 0, 0),
439 States {
440 iowait: false,
441 steal: false,
442 irq: false,
443 },
444 ms(4),
445 )
446 .unwrap();
447 assert_eq!((u.iowait, u.steal, u.irq), (None, None, None));
448 assert_eq!(u.used().to_string(), "50.0%");
449 }
450
451 #[test]
452 fn test_cpu_usage_no_time_and_backwards_counters() {
453 assert!(Usage::from_delta(&Times::default(), ALL, ms(5)).is_none());
455 assert!(times(5, 0, 0, 0, 0).since(×(6, 0, 0, 0, 0)).is_none());
456 let d = times(7, 1, 2, 0, 0).since(×(5, 1, 1, 0, 0)).unwrap();
457 assert_eq!((d.user, d.idle), (ms(2), ms(1)));
458 }
459
460 #[test]
461 fn test_cpu_sampler_live_never_out_of_range() {
462 let mut s = Sampler::new().unwrap();
463 let mut out = vec![Percent::FULL; crate::cpu::logical() + 4];
464 std::thread::sleep(ms(30));
465 match s.sample_per_core_into(&mut out) {
466 Ok(u) => {
467 assert!(u.used() <= Percent::FULL && u.interval >= ms(25));
468 assert_eq!(
469 out[crate::cpu::logical() + 3],
470 Percent::FULL,
471 "past the cores is untouched"
472 );
473 }
474 Err(Error::TooSoon { .. } | Error::Unsupported { .. }) => {}
475 Err(e) => panic!("{e}"),
476 }
477 let mut short = [Percent::ZERO; 0];
478 if crate::cpu::logical() > 0 {
479 assert!(matches!(
480 s.sample_per_core_into(&mut short),
481 Err(Error::TooLarge { .. }) | Err(Error::Unsupported { .. })
482 ));
483 }
484 std::thread::sleep(ms(30));
485 if let Ok(u) = s.sample() {
486 assert!(u.used() <= Percent::FULL);
487 }
488 let u = usage_over(ms(30)).unwrap();
489 assert!(u.used() <= Percent::FULL);
490 }
491}