Oregami
Repositories/oxedyne/fe2o3

oxedyne/fe2o3/fe2o3_sys/src/clock.rs

4.2 KiB, 1 run

created by r1870400018:65726, which is this file's identity for as long as the history lasts, whatever it is later renamed to

download · who wrote it · its history

1//! The boot clock, and noticing that the machine slept.
2//!
3//! `CLOCK_BOOTTIME` counts the time a machine is suspended; `CLOCK_MONOTONIC`, which is
4//! what [`Instant`] reads on Linux, does not. A loop timed by `Instant` therefore sleeps
5//! through a suspend without knowing: a quiet window it was measuring has the same time
6//! left on waking as it had on going down. The two clocks differ by exactly the time
7//! asleep, which is what [`Asleep`] reports.
8//!
9//! A process that is stopped (`SIGSTOP`, a debugger, a long swap-out) is not a suspend.
10//! Both clocks run through it, so they stay level and nothing is reported.
11//!
12//! The system call comes from `nix`, which owns the `unsafe` this crate forbids.
13
14use oxedyne_fe2o3_core::prelude::*;
15
16use std::time::{
17 Duration,
18 Instant,
19};
20
21use nix::time::{
22 clock_gettime,
23 ClockId,
24};
25
26pub const LEAST: Duration = Duration::from_secs(2); // the shortest absence Asleep::new reports
27
28/// Time since the kernel booted, counting any time the machine spent suspended.
29///
30/// The first field of `/proc/uptime` is the same clock.
31pub fn since_boot() -> Outcome<Duration> {
32 let ts = match clock_gettime(ClockId::CLOCK_BOOTTIME) {
33 Ok(ts) => ts,
34 Err(e) => return Err(err!(
35 "Cannot read CLOCK_BOOTTIME: {}.", e;
36 IO, System)),
37 };
38 let secs = match u64::try_from(ts.tv_sec()) {
39 Ok(s) => s,
40 Err(_) => return Err(err!(
41 "CLOCK_BOOTTIME read {} seconds, before the boot.", ts.tv_sec();
42 IO, System, Invalid)),
43 };
44 // A timespec holds under a billion nanoseconds, so the cast cannot lose any.
45 Ok(Duration::new(secs, ts.tv_nsec() as u32))
46}
47
48/// How long the machine was suspended across a stretch that the boot clock timed as `boot`
49/// and the monotonic clock as `mono`, when that is at least `least`.
50///
51/// The whole of the arithmetic, apart from reading the clocks, so a test can give it the
52/// readings a suspend would leave. A `least` above nothing is wanted because the two clocks
53/// are read a moment apart, and a smaller difference may be that moment and not a sleep.
54pub fn slept(boot: Duration, mono: Duration, least: Duration) -> Option<Duration> {
55 let gap = boot.saturating_sub(mono);
56 if !gap.is_zero() && gap >= least {
57 Some(gap)
58 } else {
59 None
60 }
61}
62
63/// A reading of both clocks, kept to be compared with the next.
64///
65/// Call [`Asleep::check`] once a turn. It answers with the time the machine was suspended
66/// since the call before, when that was at least the threshold, and starts counting afresh,
67/// so one suspend is reported once.
68#[derive(Clone, Copy, Debug)]
69pub struct Asleep {
70 boot: Duration, // CLOCK_BOOTTIME at the last check
71 seen: Instant, // the monotonic clock at the same moment
72 least: Duration, // a shorter absence is not reported
73}
74
75impl Asleep {
76
77 /// Reads both clocks now, to be reported against from here, with the threshold [`LEAST`].
78 pub fn new() -> Outcome<Self> {
79 Self::with_least(LEAST)
80 }
81
82 pub fn with_least(least: Duration) -> Outcome<Self> {
83 let boot = res!(since_boot());
84 Ok(Self::at(boot, Instant::now(), least))
85 }
86
87 /// Starts from readings the caller took, which is how a test, or a caller that reads
88 /// the clocks itself, places the baseline.
89 pub fn at(boot: Duration, seen: Instant, least: Duration) -> Self {
90 Self { boot, seen, least }
91 }
92
93 /// Reads both clocks now and compares them with the last check.
94 ///
95 /// A clock that cannot be read is no news: the check says nothing and keeps the last
96 /// reading, so the next one measures across both turns and loses no suspend.
97 pub fn check(&mut self) -> Option<Duration> {
98 match since_boot() {
99 Ok(boot) => self.check_at(boot, Instant::now()),
100 Err(_) => None,
101 }
102 }
103
104 /// As [`Asleep::check`], on readings the caller took.
105 pub fn check_at(&mut self, boot: Duration, now: Instant) -> Option<Duration> {
106 let found = slept(
107 boot.saturating_sub(self.boot),
108 now.saturating_duration_since(self.seen),
109 self.least,
110 );
111 self.boot = boot;
112 self.seen = now;
113 found
114 }
115}