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, 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}