Skip to main content

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}