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