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}