Add search for process feature and general maintenance

Author: ThetaSinner

Cargo.toml

@@ -14,13 +14,17 @@ path = "./sample/port-binder/main.rs"
 name = "proc-runner"
 path = "./sample/proc-runner/main.rs"
 
+[[bin]]
+name = "waiter"
+path = "./sample/waiter/main.rs"
+
 [dependencies]
 netstat2 = "0.9.1"
 thiserror = "1"
 retry = { version = "2.0.0", optional = true }
 tokio = { version = "1", features = ["time"], optional = true }
 async-recursion = { version = "1", optional = true }
-sysinfo = { version = "0.28.4", optional = true }
+sysinfo = { version = "0.30.10", optional = true }
 once_cell = { version = "1.17.1", optional = true }
 
 [dev-dependencies]
@@ -40,8 +44,8 @@ async = [
     "dep:async-recursion"
 ]
 
-# Included as a default feature but because sysinfo is relatively heavy-weight to initialise, its behind a feature flag
-# to allow it to be disabled if desired.
+# Included as a default feature but because sysinfo is relatively heavy-weight to initialise, so it's behind a feature
+# flag to allow it to be disabled if desired.
 proc = [
     "dep:sysinfo",
     "dep:once_cell"

README.md

@@ -16,14 +16,32 @@ let query = PortQuery::new()
 query.execute().unwrap();
 ```
 
+### Find processes by name
+
+```rust no_run
+use proc_ctl::{ProcCtlResult, ProcQuery};
+
+fn main() -> ProcCtlResult<()> {
+
+    let query = ProcQuery::new()
+        .process_name("firefox");
+
+    let processes = query.list_processes()?;
+    Ok(())
+}
+```
+
 ### Find the children of a given process
 
 ```rust no_run
-use proc_ctl::ProcQuery;
+use proc_ctl::{ProcCtlResult, ProcQuery};
 
-let query = ProcQuery::new()
+fn main() -> ProcCtlResult<()> {
+    let query = ProcQuery::new()
         .process_id(55932) // Get a process ID from somewhere
         .expect_min_num_children(1);
 
-query.children().unwrap();
+    query.children()?;
+    Ok(())
+}
 ```

run_tests.sh

@@ -3,6 +3,7 @@
 set -xue
 
 cargo test
+cargo test --no-default-features --test lib_test
 cargo test --features resilience
 cargo test --features async
 cargo test --all-features

sample/waiter/main.rs

@@ -0,0 +1,6 @@
+use std::io::stdin;
+
+fn main() {
+    println!("Waiting");
+    stdin().read_line(&mut String::new()).unwrap();
+}

src/proc_query.rs

@@ -1,11 +1,10 @@
+use crate::common::{resolve_pid, MaybeHasPid};
+use crate::{Pid, ProcCtlError, ProcCtlResult};
 use std::path::PathBuf;
 use std::process::Child;
 use std::sync::Mutex;
-// Switch to `use std::sync::OnceLock;` on the next Rust release https://github.com/rust-lang/rust/issues/74465
-use crate::common::{resolve_pid, MaybeHasPid};
-use crate::{Pid, ProcCtlError, ProcCtlResult};
-use once_cell::sync::OnceCell;
-use sysinfo::{PidExt, Process, ProcessExt, ProcessRefreshKind, RefreshKind, System, SystemExt};
+use std::sync::OnceLock;
+use sysinfo::{Process, ProcessRefreshKind, RefreshKind, System};
 
 /// Information about a process
 #[derive(Debug, Clone)]
@@ -15,21 +14,22 @@ pub struct ProcInfo {
     /// The command used to launch the process
     pub cmd: Vec<String>,
     /// The path to the executable the process is running
-    pub exe: PathBuf,
+    pub exe: Option<PathBuf>,
     /// The process ID
     pub pid: Pid,
     /// Parent process ID if relevant
     pub parent: Option<Pid>,
     /// Environment variables available to the process
     pub env: Vec<String>,
     /// The current working directory of the process
-    pub cwd: PathBuf,
+    pub cwd: Option<PathBuf>,
 }
 
 /// Get information about a process
 #[derive(Debug)]
 pub struct ProcQuery {
     process_id: Option<Pid>,
+    name: Option<String>,
     min_num_children: Option<usize>,
 }
 
@@ -38,18 +38,27 @@ impl ProcQuery {
     pub fn new() -> Self {
         ProcQuery {
             process_id: None,
+            name: None,
             min_num_children: None,
         }
     }
 
     /// Set the process ID to match
     ///
-    /// Either this function or `process_id_from_child` are required to be called before the query is usable.
+    /// One of this, [ProcQuery::process_name] or [ProcQuery::process_id_from_child] must be called before the query is usable.
     pub fn process_id(mut self, pid: Pid) -> Self {
         self.process_id = Some(pid);
         self
     }
 
+    /// Set the process name to match
+    ///
+    /// One of this, [ProcQuery::process_id] or [ProcQuery::process_id_from_child] must be called before the query is usable.
+    pub fn process_name(mut self, name: impl AsRef<str>) -> Self {
+        self.name = Some(name.as_ref().to_string());
+        self
+    }
+
     /// Get the process ID of a child process
     ///
     /// Either this function or `process_id` are required to be called before the query is usable.
@@ -63,6 +72,34 @@ impl ProcQuery {
         self
     }
 
+    /// List all processes matching the current filters.
+    pub fn list_processes(&self) -> ProcCtlResult<Vec<ProcInfo>> {
+        let mut sys_handle = sys_handle().lock().unwrap();
+        sys_handle.refresh_processes();
+        let processes = sys_handle.processes();
+        let infos: Vec<ProcInfo> = processes
+            .values()
+            .filter(|p| {
+                if let Some(pid) = self.process_id {
+                    if p.pid().as_u32() != pid {
+                        return false;
+                    }
+                }
+
+                if let Some(name) = &self.name {
+                    if p.name() != name {
+                        return false;
+                    }
+                }
+
+                true
+            })
+            .map(|p| p.into())
+            .collect();
+
+        Ok(infos)
+    }
+
     /// Find the children of the selected process
     pub fn children(&self) -> ProcCtlResult<Vec<ProcInfo>> {
         let pid = resolve_pid(self)?;
@@ -121,7 +158,7 @@ impl ProcQuery {
 }
 
 fn sys_handle() -> &'static Mutex<System> {
-    static SYS_HANDLE: OnceCell<Mutex<System>> = OnceCell::new();
+    static SYS_HANDLE: OnceLock<Mutex<System>> = OnceLock::new();
     SYS_HANDLE.get_or_init(|| {
         let mut sys = System::new_with_specifics(
             RefreshKind::new().with_processes(ProcessRefreshKind::new()),
@@ -137,11 +174,11 @@ impl From<&Process> for ProcInfo {
         ProcInfo {
             name: value.name().to_owned(),
             cmd: value.cmd().to_owned(),
-            exe: value.exe().to_owned(),
+            exe: value.exe().map(|p| p.to_owned()),
             pid: value.pid().as_u32() as Pid,
             parent: value.parent().map(|p| p.as_u32() as Pid),
             env: value.environ().to_owned(),
-            cwd: value.cwd().to_owned(),
+            cwd: value.cwd().map(|p| p.to_owned()),
         }
     }
 }

tests/lib_test.rs

@@ -1,5 +1,5 @@
 use assert_cmd::cargo::CommandCargoExt;
-use proc_ctl::{PortQuery, ProcQuery};
+use proc_ctl::PortQuery;
 use retry::delay::Fixed;
 use retry::retry;
 use std::process::Command;
@@ -88,9 +88,30 @@ async fn port_query_with_async_retry() {
     assert_eq!(1, ports.len());
 }
 
+#[cfg(feature = "proc")]
+#[test]
+fn proc_query_by_name() {
+    use proc_ctl::ProcQuery;
+
+    let mut binder = Command::cargo_bin("waiter").unwrap();
+    let mut handle = binder.spawn().unwrap();
+
+    let query = ProcQuery::new().process_name("waiter".to_string());
+
+    let processes = query.list_processes().unwrap();
+
+    handle.kill().unwrap();
+
+    println!("{:?}", processes);
+
+    assert_eq!(1, processes.len());
+}
+
 #[cfg(feature = "proc")]
 #[test]
 fn proc_query_for_children() {
+    use proc_ctl::ProcQuery;
+
     let binder = Command::cargo_bin("port-binder").unwrap();
     let port_binder_path = binder.get_program();
 
@@ -117,6 +138,7 @@ fn proc_query_for_children() {
 #[cfg(all(feature = "proc", feature = "resilience"))]
 #[test]
 fn proc_query_for_children_with_retry() {
+    use proc_ctl::ProcQuery;
     use std::time::Duration;
 
     let binder = Command::cargo_bin("port-binder").unwrap();
@@ -143,6 +165,7 @@ fn proc_query_for_children_with_retry() {
 #[cfg(all(feature = "proc", feature = "async"))]
 #[tokio::test]
 async fn proc_query_for_children_async_with_retry() {
+    use proc_ctl::ProcQuery;
     use std::time::Duration;
 
     let binder = Command::cargo_bin("port-binder").unwrap();