proc_tree/lib.rs
1//! # proc-tree
2//!
3//! Linux process tree: snapshot, incremental maintenance via fork/exec events,
4//! ancestry chain queries, and PID reuse detection.
5//!
6//! ## Quick Start
7//!
8//! ```rust
9//! use proc_tree::{ProcessStore, ProcessInfo, ProcEvent};
10//! use proc_tree::{snapshot, resolve, handle_events, build_chain_string};
11//!
12//! // Implement your own storage (or use a provided example)
13//! # struct MyStore;
14//! # impl ProcessStore for MyStore {
15//! # fn get_process(&self, pid: u32) -> Option<ProcessInfo> { None }
16//! # fn insert_process(&self, pid: u32, info: ProcessInfo) {}
17//! # fn remove_process(&self, pid: u32) -> Option<ProcessInfo> { None }
18//! # fn all_pids(&self) -> Vec<u32> { vec![] }
19//! # fn children_of(&self, pid: u32) -> Vec<u32> { vec![] }
20//! # fn for_each_child(&self, _pid: u32, _f: &mut dyn FnMut(u32)) {}
21//! # }
22//!
23//! let store = MyStore;
24//!
25//! // Seed from /proc
26//! snapshot(&store).expect("failed to read /proc");
27//!
28//! // Resolve a PID
29//! if let Some(info) = resolve(&store, 1) {
30//! println!("PID 1: cmd={}, user={}", info.cmd(), info.user());
31//! }
32//!
33//! // Build ancestry chain
34//! let s = build_chain_string(&store, 1234);
35//! println!("Chain: {}", s);
36//!
37//! // Handle events (returns ExitedProcess handles)
38//! let exited = handle_events(&store, &[
39//! ProcEvent::Fork { child_pid: 200, parent_pid: 100, timestamp_ns: 0 },
40//! ]);
41//! // Caller decides when to remove exited processes
42//! for ep in exited {
43//! ep.remove(&store);
44//! }
45//! ```
46//!
47//! ## PID Reuse Detection
48//!
49//! When a process exits and its PID is reused by a new process, cached data
50//! becomes stale. `ProcessStore` implementations should compare `start_time_ns`
51//! with the current `/proc` value to detect reuse.
52
53mod default_store;
54mod ops;
55mod proc;
56mod traits;
57mod tree;
58mod types;
59
60// Public API — types
61pub use types::ProcessInfo;
62
63// Public API — traits
64pub use traits::ProcessStore;
65
66// Public API — default implementations
67pub use default_store::DefaultStore;
68
69// Public API — tree types
70pub use tree::{ExitedProcess, ProcEvent, ProcessLink};
71
72// Public API — operations
73pub use ops::{
74 build_chain_links, build_chain_string, children, descendants, display, find_by_cmd,
75 find_by_user, handle_event, handle_events, is_descendant, resolve, siblings, snapshot,
76 tree_len,
77};
78
79// Public API — proc utilities
80pub use proc::{parse_proc_entry, read_proc_comm, read_proc_start_time_ns, uid_to_username};