pool_mod/status.rs
1//! A point-in-time snapshot of pool occupancy.
2
3/// A snapshot of how many resources a [`Pool`](crate::Pool) holds.
4///
5/// Returned by [`Pool::status`](crate::Pool::status). The counts are read under
6/// the pool's lock, but in a concurrent program they are stale the instant they
7/// are returned — treat them as a gauge for logging and metrics, not as a value
8/// to branch on for correctness.
9///
10/// The invariant `size == idle + in_use` holds for each individual snapshot.
11///
12/// # Examples
13///
14/// ```
15/// use pool_mod::{Manager, Pool};
16/// use std::convert::Infallible;
17///
18/// struct Nothing;
19/// impl Manager for Nothing {
20/// type Resource = ();
21/// type Error = Infallible;
22/// fn create(&self) -> Result<(), Infallible> { Ok(()) }
23/// fn recycle(&self, _r: &mut ()) -> Result<(), Infallible> { Ok(()) }
24/// }
25///
26/// let pool = Pool::builder(Nothing).max_size(4).min_idle(2).build()
27/// .expect("configuration is valid");
28///
29/// let status = pool.status();
30/// assert_eq!(status.size, 2);
31/// assert_eq!(status.idle, 2);
32/// assert_eq!(status.in_use, 0);
33/// assert_eq!(status.max_size, 4);
34/// assert_eq!(status.size, status.idle + status.in_use);
35/// ```
36#[must_use]
37#[derive(Debug, Clone, Copy, PartialEq, Eq)]
38pub struct Status {
39 /// Total resources the pool owns right now: idle, plus checked out, plus any
40 /// currently being created.
41 pub size: usize,
42
43 /// Resources sitting idle and available for immediate checkout.
44 pub idle: usize,
45
46 /// Resources currently lent out to callers (counted as `size - idle`, which
47 /// folds in-flight creations into the in-use figure).
48 pub in_use: usize,
49
50 /// The configured `max_size` the pool will not grow beyond.
51 pub max_size: usize,
52}