sys_lib/disk.rs
1//! Disks and filesystems: free space, the mounted filesystems, and how hard the
2//! disks are working.
3//!
4//! ```
5//! use sys_lib as sys;
6//!
7//! let s = sys::disk::space(".")?;
8//! println!("{} available of {} ({} used)", s.available, s.total, s.used_percent());
9//! # Ok::<(), sys_lib::Error>(())
10//! ```
11
12use core::time::Duration;
13use std::{
14 path::{Path, PathBuf},
15 time::Instant,
16};
17
18use crate::{Bytes, Error, Percent, Pressure, Rate, Result, origin::Origin};
19
20/// The space on one filesystem.
21#[derive(Clone, Copy, PartialEq, Eq, Debug)]
22#[non_exhaustive]
23pub struct Space {
24 /// The filesystem's size.
25 pub total: Bytes,
26 /// Every free block, the root reserve included.
27 pub free: Bytes,
28 /// What an unprivileged user can use (the root reserve excluded).
29 pub available: Bytes,
30}
31
32impl Space {
33 /// A reading with its invariants applied: `available <= free <= total`.
34 // Unused on Windows, macOS, and targets without a backend.
35 #[allow(dead_code)]
36 pub(crate) fn new(total: u64, free: u64, available: u64) -> Space {
37 let free = free.min(total);
38 Space {
39 total: Bytes::new(total),
40 free: Bytes::new(free),
41 available: Bytes::new(available.min(free)),
42 }
43 }
44
45 /// Space in use: `total - free`.
46 #[must_use]
47 pub fn used(&self) -> Bytes {
48 self.total.saturating_sub(self.free)
49 }
50
51 /// [`used`](Space::used) as a share of `total`.
52 #[must_use]
53 pub fn used_percent(&self) -> Percent {
54 self.used().percent_of(self.total)
55 }
56}
57
58/// The space on the filesystem holding `path`: one system call, no
59/// allocation.
60///
61/// This blocks if `path` is on a dead network mount: pointing it there is the
62/// caller's choice.
63///
64/// ```
65/// use sys_lib as sys;
66///
67/// let s = sys::disk::space(".")?;
68/// if s.available < sys::Bytes::from_gib(10) { /* refuse compaction */ }
69/// # Ok::<(), sys_lib::Error>(())
70/// ```
71///
72/// # Errors
73///
74/// `NotFound` when `path` does not exist; `PermissionDenied`; `Os` when the
75/// call fails.
76pub fn space(path: impl AsRef<Path>) -> Result<Space> {
77 crate::sys::disk_space(path.as_ref())
78}
79
80/// One mounted filesystem.
81#[derive(Clone, Debug, PartialEq, Eq)]
82#[non_exhaustive]
83pub struct Disk {
84 /// Where it is mounted.
85 pub mount_point: PathBuf,
86 /// The device: `/dev/nvme0n1p2`, `C:`, `\\?\Volume{...}\`.
87 pub device: String,
88 /// The volume label (Windows, macOS).
89 pub label: Option<String>,
90 /// The filesystem type: `ext4`, `btrfs`, `apfs`, `NTFS`, `overlay`.
91 pub filesystem: String,
92 /// What kind of storage it is.
93 pub kind: DiskKind,
94 /// The space, or `None` for media not present (an empty card reader) and
95 /// network mounts.
96 pub space: Option<Space>,
97 /// Mounted read-only.
98 pub read_only: bool,
99 /// On removable media.
100 pub removable: bool,
101}
102
103/// What kind of storage a [`Disk`] is on. Telling solid-state from rotating
104/// disks arrives in 0.5 (DSK-04); until then a fixed local disk is `Unknown`.
105#[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
106#[non_exhaustive]
107pub enum DiskKind {
108 /// Solid-state.
109 Ssd,
110 /// Rotating.
111 Hdd,
112 /// Removable media (USB sticks, card readers).
113 Removable,
114 /// A network filesystem.
115 Network,
116 /// Optical media.
117 Optical,
118 /// Memory-backed (`tmpfs`, a RAM disk).
119 Ram,
120 /// A virtual disk or filesystem (an overlay root in a container).
121 Virtual,
122 /// Not known.
123 Unknown,
124}
125
126/// Which filesystems [`list_with`] includes.
127#[derive(Clone, Copy, Debug)]
128#[non_exhaustive]
129pub struct ListOptions {
130 /// Include network filesystems (default false: `statvfs` on a dead NFS
131 /// mount can hang).
132 pub include_network: bool,
133 /// Include pseudo filesystems: `proc`, `sysfs`, `cgroup`, `tmpfs`,
134 /// `devtmpfs`, `squashfs`, ... (default false).
135 pub include_pseudo: bool,
136 /// Include bind mounts and further mounts of one filesystem (default
137 /// false: each filesystem once, by device number).
138 pub include_duplicates: bool,
139 /// The most mounts read; more is `TooLarge` (default 4 096).
140 pub max_mounts: usize,
141}
142
143impl Default for ListOptions {
144 fn default() -> Self {
145 ListOptions {
146 include_network: false,
147 include_pseudo: false,
148 include_duplicates: false,
149 max_mounts: 4_096,
150 }
151 }
152}
153
154/// The local, real filesystems, sorted by mount point, each once.
155///
156/// Never blocks on a dead network mount (network filesystems are left out),
157/// and on Windows never pops up "insert a disk" for an empty drive (threat
158/// T8). Inside a container it shows the container's mounts.
159///
160/// ```
161/// for d in sys_lib::disk::list()? {
162/// println!("{:<20} {:<8} {:?} {:?}", d.mount_point.display(), d.filesystem, d.kind, d.space.map(|s| s.available));
163/// }
164/// # Ok::<(), sys_lib::Error>(())
165/// ```
166///
167/// # Errors
168///
169/// `TooLarge` with more than 4 096 mounts; `NotFound` when the mount table is
170/// hidden.
171pub fn list() -> Result<Vec<Disk>> {
172 list_with(ListOptions::default())
173}
174
175/// The filesystems `options` selects, sorted by mount point.
176///
177/// ```
178/// use sys_lib::disk::{self, ListOptions};
179///
180/// let mut options = ListOptions::default();
181/// options.include_network = true; // accept the risk of a hang on a dead mount
182/// let all = disk::list_with(options)?;
183/// # Ok::<(), sys_lib::Error>(())
184/// ```
185///
186/// # Errors
187///
188/// As [`list`], with `options.max_mounts` as the budget.
189pub fn list_with(options: ListOptions) -> Result<Vec<Disk>> {
190 let mut disks = crate::sys::disks(&options)?;
191 disks.sort_by(|a, b| a.mount_point.cmp(&b.mount_point));
192 Ok(disks)
193}
194
195/// The mount holding `path`. Only that filesystem is asked for its space, so a
196/// dead network mount elsewhere does not matter; `path` on one blocks.
197///
198/// ```
199/// let d = sys_lib::disk::of(".")?;
200/// println!("{} on {} ({:?})", d.filesystem, d.mount_point.display(), d.kind);
201/// # Ok::<(), sys_lib::Error>(())
202/// ```
203///
204/// # Errors
205///
206/// `NotFound` when `path` does not exist or the mount table is hidden;
207/// `PermissionDenied` when it cannot be reached.
208pub fn of(path: impl AsRef<Path>) -> Result<Disk> {
209 crate::sys::disk_of(path.as_ref())
210}
211
212/// The interval [`io`] measures over: 1 s.
213pub const DEFAULT_WINDOW: Duration = Duration::from_secs(1);
214
215const MIN_WINDOW: Duration = Duration::from_millis(100);
216const MAX_WINDOW: Duration = Duration::from_secs(60);
217
218/// How hard the disks worked over an interval.
219#[derive(Clone, Copy, PartialEq, Debug)]
220#[non_exhaustive]
221pub struct DiskIo {
222 /// Read speed.
223 pub read: Rate,
224 /// Write speed.
225 pub write: Rate,
226 /// Read operations per second.
227 pub reads_per_sec: f64,
228 /// Write operations per second.
229 pub writes_per_sec: f64,
230 /// The share of the interval with I/O in flight, when reported.
231 pub busy: Option<Percent>,
232 /// The time per completed operation, when reported.
233 pub average_latency: Option<Duration>,
234 /// The time the values cover.
235 pub interval: Duration,
236}
237
238/// Cumulative I/O counters since boot.
239#[derive(Clone, Copy, PartialEq, Eq, Debug, Default)]
240#[non_exhaustive]
241pub struct IoTotals {
242 /// Bytes read.
243 pub read: Bytes,
244 /// Bytes written.
245 pub written: Bytes,
246 /// Read operations completed.
247 pub reads: u64,
248 /// Write operations completed.
249 pub writes: u64,
250 /// Time with I/O in flight, when reported.
251 pub io_time: Option<Duration>,
252}
253
254/// One disk's rates.
255#[derive(Clone, Debug, PartialEq)]
256#[non_exhaustive]
257pub struct DeviceIo {
258 /// The disk: `nvme0n1`, `disk0`, `PhysicalDrive0`.
259 pub device: String,
260 /// Its rates.
261 pub io: DiskIo,
262}
263
264/// One disk's cumulative counters.
265#[derive(Clone, Debug, PartialEq, Eq)]
266#[non_exhaustive]
267pub struct IoCounters {
268 /// The disk: `nvme0n1`, `disk0`, `PhysicalDrive0`.
269 pub device: String,
270 /// Its counters.
271 pub totals: IoTotals,
272}
273
274/// Cumulative counters as a platform reports them.
275#[derive(Clone, Copy, PartialEq, Eq, Debug, Default)]
276pub(crate) struct DiskRaw {
277 pub(crate) read: u64,
278 pub(crate) written: u64,
279 pub(crate) reads: u64,
280 pub(crate) writes: u64,
281 /// Time with I/O in flight.
282 pub(crate) busy: Option<Duration>,
283 /// Time spent on completed operations (read plus write).
284 pub(crate) op_time: Option<Duration>,
285 /// How many disks the counters cover (1 for one disk), so a sum's busy
286 /// time becomes the mean share across disks.
287 pub(crate) disks: u32,
288}
289
290impl DiskRaw {
291 #[cfg_attr(not(any(target_os = "linux", target_os = "android")), allow(dead_code))] // the platforms that sum or build these
292 pub(crate) fn add(&mut self, other: &DiskRaw) {
293 self.read = self.read.saturating_add(other.read);
294 self.written = self.written.saturating_add(other.written);
295 self.reads = self.reads.saturating_add(other.reads);
296 self.writes = self.writes.saturating_add(other.writes);
297 self.busy = add_opt(self.busy, other.busy);
298 self.op_time = add_opt(self.op_time, other.op_time);
299 self.disks = self.disks.saturating_add(other.disks);
300 }
301
302 fn totals(&self) -> IoTotals {
303 IoTotals {
304 read: Bytes::new(self.read),
305 written: Bytes::new(self.written),
306 reads: self.reads,
307 writes: self.writes,
308 io_time: self.busy,
309 }
310 }
311
312 /// The rates between `earlier` and `self`. A counter that went backwards
313 /// (a disk removed and re-attached) counts as no activity: the caller
314 /// re-bases.
315 fn rates_since(&self, earlier: &DiskRaw, interval: Duration) -> DiskIo {
316 let d = |new: u64, old: u64| new.saturating_sub(old);
317 let secs = interval.as_secs_f64();
318 let ops = d(self.reads, earlier.reads).saturating_add(d(self.writes, earlier.writes));
319 let per_sec = |n: u64| if secs > 0.0 { n as f64 / secs } else { 0.0 };
320 DiskIo {
321 read: Rate::from_delta(d(self.read, earlier.read), interval),
322 write: Rate::from_delta(d(self.written, earlier.written), interval),
323 reads_per_sec: per_sec(d(self.reads, earlier.reads)),
324 writes_per_sec: per_sec(d(self.writes, earlier.writes)),
325 // Several disks: the mean share of the interval each was busy.
326 busy: match (self.busy, earlier.busy) {
327 (Some(n), Some(o)) if !interval.is_zero() => Some(Percent::from_ratio_u128(
328 n.checked_sub(o).unwrap_or_default().as_nanos(),
329 interval.as_nanos() * u128::from(self.disks.max(1)),
330 )),
331 _ => None,
332 },
333 average_latency: match (self.op_time, earlier.op_time) {
334 (Some(n), Some(o)) if ops > 0 => {
335 let spent = n.checked_sub(o).unwrap_or_default();
336 Some(spent / u32::try_from(ops).unwrap_or(u32::MAX))
337 }
338 _ => None,
339 },
340 interval,
341 }
342 }
343}
344
345#[cfg_attr(not(any(target_os = "linux", target_os = "android")), allow(dead_code))]
346fn add_opt(a: Option<Duration>, b: Option<Duration>) -> Option<Duration> {
347 match (a, b) {
348 (Some(a), Some(b)) => Some(a.saturating_add(b)),
349 (a, None) => a,
350 (None, b) => b,
351 }
352}
353
354/// Disk activity over the next second, every physical disk together.
355/// **Blocks for [`DEFAULT_WINDOW`]**; a monitor keeps an [`IoSampler`].
356///
357/// Only physical disks are counted (partitions, device-mapper and RAID
358/// members, loop, RAM, and zram devices are left out), so nothing is counted
359/// twice. Inside a container the disks are the host's; this process's own I/O
360/// is [`process::io`](crate::process::io).
361///
362/// ```
363/// let io = sys_lib::disk::io()?; // blocks 1 s
364/// println!("read {} write {} ({:.0} IOPS, busy {:?})", io.read, io.write, io.reads_per_sec + io.writes_per_sec, io.busy);
365/// # Ok::<(), sys_lib::Error>(())
366/// ```
367///
368/// # Errors
369///
370/// As [`IoSampler::sample`].
371pub fn io() -> Result<DiskIo> {
372 io_over(DEFAULT_WINDOW)
373}
374
375/// Disk activity over `window`, clamped to 100 ms ..= 60 s. **Blocks for the
376/// window.**
377///
378/// # Errors
379///
380/// As [`IoSampler::sample`].
381pub fn io_over(window: Duration) -> Result<DiskIo> {
382 let mut sampler = IoSampler::totals_only()?;
383 std::thread::sleep(window.clamp(MIN_WINDOW, MAX_WINDOW));
384 sampler.sample()
385}
386
387/// Bytes and operations since boot, every physical disk together: one read,
388/// no waiting, no allocation.
389///
390/// # Errors
391///
392/// `NotFound` when the counters are hidden; `Malformed`; `Unsupported` where
393/// the OS gives no disk counters to an unprivileged process.
394pub fn io_totals() -> Result<IoTotals> {
395 crate::sys::disk_io_totals().map(|r| r.totals())
396}
397
398/// The cumulative counters of each physical disk (Tier 2).
399///
400/// # Errors
401///
402/// As [`io_totals`].
403pub fn io_counters() -> Result<Vec<IoCounters>> {
404 Ok(crate::sys::disk_io_counters()?
405 .into_iter()
406 .map(|(device, raw)| IoCounters {
407 device,
408 totals: raw.totals(),
409 })
410 .collect())
411}
412
413/// How much time tasks were stalled on I/O ([`Pressure`]). Linux: the cgroup's
414/// `io.pressure`, else `/proc/pressure/io`. macOS and Windows: `None`.
415///
416/// ```
417/// use sys_lib::{self as sys, PressureLevel};
418///
419/// if let Some(p) = sys::disk::pressure()? {
420/// if p.level >= PressureLevel::Warning { /* postpone compaction */ }
421/// }
422/// # Ok::<(), sys_lib::Error>(())
423/// ```
424///
425/// # Errors
426///
427/// `Malformed` when the kernel's file does not parse.
428pub fn pressure() -> Result<Option<Pressure>> {
429 crate::sys::disk_pressure()
430}
431
432/// Measures disk activity between samples. Owned by the caller. `sample`
433/// never blocks and allocates nothing.
434///
435/// ```no_run
436/// use std::time::Duration;
437///
438/// let mut disks = sys_lib::disk::IoSampler::new()?;
439/// std::thread::sleep(Duration::from_secs(5));
440/// let io = disks.sample()?;
441/// println!("read {} write {}", io.read, io.write);
442/// for d in disks.sample_per_disk()? {
443/// println!(" {}: busy {:?}", d.device, d.io.busy);
444/// }
445/// # Ok::<(), sys_lib::Error>(())
446/// ```
447#[derive(Debug)]
448pub struct IoSampler {
449 total: DiskRaw,
450 at: Instant,
451 devices: Vec<(String, DiskRaw)>,
452 devices_at: Instant,
453 origin: Origin,
454}
455
456impl IoSampler {
457 /// Takes the first reading, of the total and of each disk.
458 ///
459 /// # Errors
460 ///
461 /// As [`io_totals`].
462 pub fn new() -> Result<IoSampler> {
463 Self::from(Origin::local())
464 }
465
466 /// [`new`](IoSampler::new), reading from `origin`.
467 pub(crate) fn from(origin: Origin) -> Result<IoSampler> {
468 let now = Instant::now();
469 Ok(IoSampler {
470 total: origin.disk_io_totals()?,
471 at: now,
472 devices: origin.disk_io_counters()?,
473 devices_at: now,
474 origin,
475 })
476 }
477
478 fn totals_only() -> Result<IoSampler> {
479 let now = Instant::now();
480 Ok(IoSampler {
481 total: crate::sys::disk_io_totals()?,
482 at: now,
483 devices: Vec::new(),
484 devices_at: now,
485 origin: Origin::local(),
486 })
487 }
488
489 /// Activity since the previous sample, every physical disk together. A
490 /// counter that went backwards re-bases the sampler and reads as no
491 /// activity for that interval.
492 ///
493 /// # Errors
494 ///
495 /// `TooSoon` when no time passed since the previous sample.
496 pub fn sample(&mut self) -> Result<DiskIo> {
497 let now = self.origin.disk_io_totals()?;
498 let at = Instant::now();
499 let interval = at.duration_since(self.at);
500 if interval.is_zero() {
501 return Err(too_soon(interval));
502 }
503 let io = now.rates_since(&self.total, interval);
504 self.total = now;
505 self.at = at;
506 Ok(io)
507 }
508
509 /// Activity since the previous per-disk sample, for each disk (allocates
510 /// the `Vec`). A disk seen for the first time reads as no activity.
511 ///
512 /// # Errors
513 ///
514 /// `TooSoon` when no time passed since the previous sample.
515 pub fn sample_per_disk(&mut self) -> Result<Vec<DeviceIo>> {
516 let now = self.origin.disk_io_counters()?;
517 let at = Instant::now();
518 let interval = at.duration_since(self.devices_at);
519 if interval.is_zero() {
520 return Err(too_soon(interval));
521 }
522 let out = now
523 .iter()
524 .map(|(device, raw)| {
525 let earlier = self
526 .devices
527 .iter()
528 .find(|(d, _)| d == device)
529 .map_or(*raw, |(_, r)| *r);
530 DeviceIo {
531 device: device.clone(),
532 io: raw.rates_since(&earlier, interval),
533 }
534 })
535 .collect();
536 self.devices = now;
537 self.devices_at = at;
538 Ok(out)
539 }
540}
541
542fn too_soon(elapsed: Duration) -> Error {
543 Error::TooSoon {
544 elapsed,
545 minimum: Duration::from_millis(1),
546 }
547}
548
549#[cfg(test)]
550mod tests {
551 use super::*;
552
553 #[test]
554 fn test_disk_busy_across_two_disks_is_the_mean() {
555 let one = |busy_ms: u64| DiskRaw {
556 busy: Some(Duration::from_millis(busy_ms)),
557 disks: 1,
558 ..DiskRaw::default()
559 };
560 let (mut before, mut after) = (one(0), one(600));
561 before.add(&one(0));
562 after.add(&one(600));
563 let io = after.rates_since(&before, Duration::from_secs(1));
564 assert_eq!(io.busy.unwrap().to_string(), "60.0%");
565 }
566
567 #[test]
568 fn test_disk_space_invariants() {
569 let s = Space::new(100, 150, 200);
570 assert_eq!(
571 (s.total.raw(), s.free.raw(), s.available.raw()),
572 (100, 100, 100)
573 );
574 let s = Space::new(1000, 400, 300);
575 assert_eq!(s.used().raw(), 600);
576 assert_eq!(s.used_percent().to_string(), "60.0%");
577 assert_eq!(Space::new(0, 0, 0).used_percent(), Percent::ZERO);
578 }
579
580 #[test]
581 fn test_disk_rates_and_backwards_counters() {
582 let a = DiskRaw {
583 read: 1 << 20,
584 written: 0,
585 reads: 10,
586 writes: 0,
587 busy: Some(Duration::from_millis(100)),
588 op_time: Some(Duration::from_millis(20)),
589 disks: 1,
590 };
591 let b = DiskRaw {
592 read: 3 << 20,
593 written: 1 << 20,
594 reads: 30,
595 writes: 10,
596 busy: Some(Duration::from_millis(600)),
597 op_time: Some(Duration::from_millis(80)),
598 disks: 1,
599 };
600 let io = b.rates_since(&a, Duration::from_secs(1));
601 assert_eq!(io.read.to_string(), "2 MiB/s");
602 assert_eq!(io.write.to_string(), "1 MiB/s");
603 assert!((io.reads_per_sec - 20.0).abs() < 1e-9 && (io.writes_per_sec - 10.0).abs() < 1e-9);
604 assert_eq!(io.busy.unwrap().to_string(), "50.0%");
605 assert_eq!(io.average_latency, Some(Duration::from_millis(2)));
606 // A disk re-attached: every counter went backwards. No negative rates.
607 let back = a.rates_since(&b, Duration::from_secs(1));
608 assert_eq!((back.read, back.write), (Rate::ZERO, Rate::ZERO));
609 assert_eq!(back.busy.unwrap(), Percent::ZERO);
610 assert_eq!(back.average_latency, None);
611 }
612
613 #[test]
614 fn test_disk_live_space_and_list() {
615 let s = space(".").unwrap();
616 assert!(s.total.raw() > 0 && s.available <= s.free && s.free <= s.total);
617 let disks = list().unwrap();
618 assert!(
619 disks
620 .windows(2)
621 .all(|w| w[0].mount_point <= w[1].mount_point)
622 );
623 for d in &disks {
624 assert!(!d.filesystem.is_empty(), "{d:?}");
625 }
626 assert!(matches!(space("/definitely/not/here/sys-lib"), Err(e) if e.is_unavailable()));
627 }
628}