From 12bcd33ec5533ba13704d86a1cf391c9e34c060c Mon Sep 17 00:00:00 2001 From: Andrew Chin Date: Fri, 22 Sep 2023 20:26:28 -0400 Subject: [PATCH] Add some more documentation for WithSystemInfo functions --- procfs-core/src/lib.rs | 68 ++++++++++++++++----------------- procfs-core/src/process/stat.rs | 24 ++++++++++++ procfs/src/lib.rs | 3 ++ 3 files changed, 60 insertions(+), 35 deletions(-) diff --git a/procfs-core/src/lib.rs b/procfs-core/src/lib.rs index 352b62ff..8ad75adc 100644 --- a/procfs-core/src/lib.rs +++ b/procfs-core/src/lib.rs @@ -8,42 +8,10 @@ //! This is a pseudo-filesystem which is available on most every linux system and provides an //! interface to kernel data structures. //! +//! # `procfs-core` //! -//! # Kernel support -//! -//! Not all fields/data are available in each kernel. Some fields were added in specific kernel -//! releases, and other fields are only present in certain kernel configuration options are -//! enabled. These are represented as `Option` fields in this crate. -//! -//! This crate aims to support all 2.6 kernels (and newer). WSL2 is also supported. -//! -//! # Documentation -//! -//! In almost all cases, the documentation is taken from the -//! [`proc.5`](http://man7.org/linux/man-pages/man5/proc.5.html) manual page. This means that -//! sometimes the style of writing is not very "rusty", or may do things like reference related files -//! (instead of referencing related structs). Contributions to improve this are welcome. -//! -//! # Panicing -//! -//! While previous versions of the library could panic, this current version aims to be panic-free -//! in a many situations as possible. Whenever the procfs crate encounters a bug in its own -//! parsing code, it will return an [`InternalError`](enum.ProcError.html#variant.InternalError) error. This should be considered a -//! bug and should be [reported](https://github.com/eminence/procfs). If you encounter a panic, -//! please report that as well. -//! -//! # Cargo features -//! -//! The following cargo features are available: -//! -//! * `chrono` -- Default. Optional. This feature enables a few methods that return values as `DateTime` objects. -//! * `backtrace` -- Optional. This feature lets you get a stack trace whenever an `InternalError` is raised. -//! -//! # Examples -//! -//! Examples can be found in the various modules shown below, or in the -//! [examples](https://github.com/eminence/procfs/tree/master/examples) folder of the code repository. -//! +//! The `procfs-core` crate is a fully platform-independent crate that contains most of the data-structures and +//! parsing code. Most people should first look at the `procfs` crate instead. use bitflags::bitflags; @@ -252,6 +220,36 @@ macro_rules! from_str { } /// Auxiliary system information interface. +/// +/// A few function in this crate require some extra system info to compute their results. For example, +/// the [crate::process::Stat::rss_bytes()] function needs to know the page size. Since `procfs-core` only parses +/// data and never interacts with a real system, this `SystemInfoInterface` is what allows real system info to be used. +/// +/// If you are a user of the `procfs` crate, you'll normally use the `[procfs::WithCurrentSystemInfo]` trait. +/// For example: +/// +/// ```rust,skip +/// use procfs::WithCurrentSystemInfo; +/// +/// let me = procfs::process::Process::myself().unwrap(); +/// let stat = me.stat().unwrap(); +/// let bytes = stat.rss_bytes().get(); +/// ``` +/// +/// However, imagine that you captured a process's stat info, along with page size: +/// ```rust +/// # let stat_data = let stat_data = std::io::Cursor::new(b"475071 (cat) R 323893 475071 323893 34826 475071 4194304 94 0 0 0 0 0 0 0 20 0 1 0 201288208 5738496 225 18446744073709551615 94881179934720 94881179954601 140722831478832 0 0 0 0 0 0 0 0 0 17 4 0 0 0 0 0 94881179970608 94881179972224 94881184485376 140722831483757 140722831483777 140722831483777 140722831486955 0"); +/// let stat = procfs_core::process::Stat::from_read(stat_data).unwrap(); +/// +/// let system_info = procfs_core::ExplicitSystemInfo { +/// boot_time_secs: 1692972606, +/// ticks_per_second: 100, +/// page_size: 4096, +/// is_little_endian: true, +/// }; +/// +/// let rss_bytes = stat.rss_bytes().with_system_info(&system_info); +/// ``` pub trait SystemInfoInterface { fn boot_time_secs(&self) -> ProcResult; fn ticks_per_second(&self) -> u64; diff --git a/procfs-core/src/process/stat.rs b/procfs-core/src/process/stat.rs index 79179220..114a05ee 100644 --- a/procfs-core/src/process/stat.rs +++ b/procfs-core/src/process/stat.rs @@ -393,6 +393,19 @@ impl Stat { /// See also the [`starttime`](struct.Stat.html#structfield.starttime) field. /// /// This function requires the "chrono" features to be enabled (which it is by default). + /// + /// Since computing the absolute start time requires knowing the current boot time, this function returns + /// a type that needs info about the current machine. + /// + /// # Example + /// + /// ```rust,skip + /// use procfs::WithCurrentSystemInfo; + /// + /// let me = procfs::process::Process::myself().unwrap(); + /// let stat = me.stat().unwrap(); + /// let start = stat.starttime().get().unwrap(); + /// ``` #[cfg(feature = "chrono")] pub fn starttime(&self) -> impl crate::WithSystemInfo>> { move |si: &crate::SystemInfo| { @@ -405,6 +418,17 @@ impl Stat { /// Gets the Resident Set Size (in bytes) /// /// The `rss` field will return the same value in pages + /// + /// # Example + /// + /// Calculating the rss value in bytes requires knowing the page size, so a `SystemInfo` is needed. + /// ```rust,skip + /// use procfs::WithCurrentSystemInfo; + /// + /// let me = procfs::process::Process::myself().unwrap(); + /// let stat = me.stat().unwrap(); + /// let bytes = stat.rss_bytes().get(); + /// ``` pub fn rss_bytes(&self) -> impl crate::WithSystemInfo { move |si: &crate::SystemInfo| self.rss * si.page_size() } diff --git a/procfs/src/lib.rs b/procfs/src/lib.rs index 2c04d8f3..a8d23f2d 100644 --- a/procfs/src/lib.rs +++ b/procfs/src/lib.rs @@ -75,6 +75,9 @@ pub trait Current: FromRead { } } +/// A type for accessing data about the currently running machine +/// +/// For more details, see the [SystemInfoInterface] trait. pub struct LocalSystemInfo; impl SystemInfoInterface for LocalSystemInfo {