Skip to main content

sys_lib/
sensors.rs

1//! Temperatures.
2//!
3//! Only documented, unprivileged sources are read. Linux has them for most
4//! sensors (`hwmon`, thermal zones); Windows has them for NVMe drives only, and
5//! macOS for none (Apple silicon sensors need private HID APIs and Intel SMC
6//! keys are undocumented), so both answer what they can and nothing else.
7//! Inside Docker and WSL the sensors are usually hidden: an empty list, not an
8//! error.
9//!
10//! ```
11//! use sys_lib as sys;
12//!
13//! match sys::sensors::temperatures() {
14//!     Ok(list) => {
15//!         for t in list {
16//!             println!("{:<16} {:?} {:.1} C (critical {:?})", t.label, t.kind, t.celsius, t.critical);
17//!         }
18//!     }
19//!     Err(e) if e.is_unavailable() => println!("no temperatures here"),
20//!     Err(e) => return Err(e),
21//! }
22//! # Ok::<(), sys_lib::Error>(())
23//! ```
24
25use crate::Result;
26
27/// One temperature sensor.
28#[derive(Clone, Debug, PartialEq)]
29#[non_exhaustive]
30pub struct Temperature {
31    /// What the OS calls it: "Package id 0", "Composite", "edge".
32    pub label: String,
33    /// What it measures.
34    pub kind: SensorKind,
35    /// The reading.
36    pub celsius: f32,
37    /// Where the hardware starts to complain, when it says.
38    pub high: Option<f32>,
39    /// Where the hardware shuts down or throttles hard, when it says.
40    pub critical: Option<f32>,
41}
42
43/// What a sensor measures.
44#[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
45#[non_exhaustive]
46pub enum SensorKind {
47    /// The CPU package or a core.
48    Cpu,
49    /// A graphics adapter.
50    Gpu,
51    /// A drive.
52    Storage,
53    /// A battery.
54    Battery,
55    /// The board, the chassis, or an ACPI zone.
56    Ambient,
57    /// Anything else.
58    Other,
59}
60
61impl SensorKind {
62    /// A short lowercase name: `"cpu"`, `"storage"`.
63    #[must_use]
64    pub const fn name(self) -> &'static str {
65        match self {
66            Self::Cpu => "cpu",
67            Self::Gpu => "gpu",
68            Self::Storage => "storage",
69            Self::Battery => "battery",
70            Self::Ambient => "ambient",
71            Self::Other => "other",
72        }
73    }
74}
75
76/// Every temperature the OS reports without privileges, in the order it lists
77/// them. Readings outside -60 to 250 degrees are left out: they are absent
78/// sensors that report a placeholder.
79///
80/// # Errors
81///
82/// `Unsupported` on macOS, iOS, and targets without a backend; `Io` when the
83/// sensor directory cannot be listed.
84pub fn temperatures() -> Result<Vec<Temperature>> {
85    crate::sys::temperatures()
86}
87
88/// Whether a reading is a temperature rather than a placeholder.
89#[allow(dead_code)] // unused on targets without a backend
90pub(crate) fn plausible(celsius: f32) -> bool {
91    (-60.0..=250.0).contains(&celsius)
92}
93
94#[cfg(test)]
95mod tests {
96    use super::*;
97
98    #[test]
99    fn test_sensors_live_list_or_unavailable() {
100        match temperatures() {
101            Ok(list) => {
102                for t in list {
103                    assert!(plausible(t.celsius), "{t:?}");
104                    assert!(!t.label.is_empty());
105                }
106            }
107            Err(e) => assert!(e.is_unavailable(), "{e}"),
108        }
109    }
110
111    #[test]
112    fn test_sensors_plausible_bounds() {
113        assert!(plausible(45.0) && plausible(-20.0));
114        assert!(!plausible(-273.0) && !plausible(511.0) && !plausible(f32::NAN));
115    }
116}