Skip to main content

docsrs_cli/
concurrency.rs

1//! Bounded concurrency budget for the multi-thread one-shot runtime.
2//!
3//! # Workload classification (Rules Rust — parallelism)
4//!
5//! - **Class:** mixed — I/O-bound HTTPS on the Tokio multi-thread runtime plus
6//!   CPU-bound HTML/JSON parse on the `spawn_blocking` pool.
7//! - **Stages:** (1) network/cache GET on async workers → (2) body decode +
8//!   scrape/markdown on blocking workers gated by this budget → (3) emit.
9//! - **Bound:** every fan-out of CPU work acquires a permit from
10//!   [`ConcurrencyBudget`]'s `Arc<Semaphore>`. Drop of the permit (RAII) returns
11//!   capacity. HTTP remains one in-flight request per command today; the same
12//!   budget is ready for multi-GET fan-out if a batch command is added.
13//! - **Formula (auto):** `min(cpus, floor((free_ram_mib / 2) / RAM_PER_TASK_MIB))`
14//!   clamped to `[1, MAX_AUTO_CONCURRENCY]`. Free RAM uses `MemAvailable` on
15//!   Linux (`/proc/meminfo`); other platforms fall back to CPU count only.
16//! - **RSS ground truth:** `RAM_PER_TASK_MIB` rounds up a single HTML parse of a
17//!   body near `HARD_MAX_BODY_BYTES` (10 MiB body + DOM + markdown ≈ 2–3× peak).
18//!   Re-measure with `/usr/bin/time -v docsrs-cli search-in-crate …` when the
19//!   body cap or scraper stack changes materially.
20//! - **Override:** CLI `--max-concurrency=N`, env `DOCSRS_CLI_MAX_CONCURRENCY`,
21//!   or `max_concurrency` in XDG `config.toml`. `0` / omit = auto formula.
22
23use std::fs;
24use std::sync::Arc;
25
26use tokio::sync::{OwnedSemaphorePermit, Semaphore};
27
28use crate::error::{AppError, AppResult, ErrorKind};
29
30/// Estimated peak RSS (MiB) for one CPU-bound parse task.
31///
32/// Derived from body hard cap (10 MiB) plus scraper DOM and markdown conversion
33/// headroom; rounded up with margin. Not a live measurement — revalidate with
34/// `/usr/bin/time -v` when parse deps or body caps change.
35pub const RAM_PER_TASK_MIB: u64 = 48;
36
37/// Hard ceiling for auto-computed concurrency (CLI, not a server farm).
38pub const MAX_AUTO_CONCURRENCY: usize = 32;
39
40/// Hard ceiling for explicit `--max-concurrency` / config override.
41pub const MAX_EXPLICIT_CONCURRENCY: usize = 256;
42
43/// Shared admission gate for CPU-bound (and future multi-GET) work.
44#[derive(Debug, Clone)]
45pub struct ConcurrencyBudget {
46    max: usize,
47    semaphore: Arc<Semaphore>,
48}
49
50impl ConcurrencyBudget {
51    /// Build a budget from a resolved permit count (`0` is invalid; use
52    /// [`resolve_max_concurrency`] first).
53    pub fn new(max: usize) -> Self {
54        let max = max.max(1);
55        Self {
56            max,
57            semaphore: Arc::new(Semaphore::new(max)),
58        }
59    }
60
61    /// Resolve auto/override then build.
62    pub fn from_configured(configured: u32) -> Self {
63        Self::new(resolve_max_concurrency(configured))
64    }
65
66    /// Configured / auto-resolved maximum concurrent CPU tasks.
67    pub fn max(&self) -> usize {
68        self.max
69    }
70
71    /// Permits currently free (observability / doctor).
72    pub fn available_permits(&self) -> usize {
73        self.semaphore.available_permits()
74    }
75
76    /// Clone of the inner semaphore for `acquire_owned` at spawn sites.
77    pub fn semaphore(&self) -> Arc<Semaphore> {
78        Arc::clone(&self.semaphore)
79    }
80
81    /// Acquire one permit (RAII). Prefer [`Self::run_cpu_bound`] for spawn paths.
82    pub async fn acquire_owned(&self) -> AppResult<OwnedSemaphorePermit> {
83        self.semaphore
84            .clone()
85            .acquire_owned()
86            .await
87            .map_err(|_| AppError::new(ErrorKind::Internal, "concurrency semaphore closed"))
88    }
89
90    /// Run CPU / blocking work on Tokio's blocking pool under this budget.
91    ///
92    /// Acquires a permit before `spawn_blocking`; the permit is held until the
93    /// closure returns (dropped inside the blocking thread).
94    ///
95    /// # Errors
96    ///
97    /// Propagates closure errors. Maps worker panic to [`ErrorKind::Internal`]
98    /// and abort/cancel to [`ErrorKind::Interrupted`].
99    pub async fn run_cpu_bound<F, T>(&self, f: F) -> AppResult<T>
100    where
101        F: FnOnce() -> AppResult<T> + Send + 'static,
102        T: Send + 'static,
103    {
104        let permit = self.acquire_owned().await?;
105        let join = tokio::task::spawn_blocking(move || {
106            let _permit = permit;
107            f()
108        });
109        match join.await {
110            Ok(inner) => inner,
111            Err(e) if e.is_cancelled() => Err(AppError::interrupted()),
112            Err(e) if e.is_panic() => Err(AppError::with_source(
113                ErrorKind::Internal,
114                "CPU worker panicked during parse",
115                e,
116            )),
117            Err(e) => Err(AppError::with_source(
118                ErrorKind::Internal,
119                "CPU worker join failed",
120                e,
121            )),
122        }
123    }
124}
125
126/// Resolve permit count from config override (`0` = auto).
127///
128/// Auto formula (documented at module root):
129/// `min(cpus, max(1, (free_ram_mib / 2) / RAM_PER_TASK_MIB))` then clamp
130/// to `[1, MAX_AUTO_CONCURRENCY]`.
131pub fn resolve_max_concurrency(configured: u32) -> usize {
132    if configured > 0 {
133        return (configured as usize).clamp(1, MAX_EXPLICIT_CONCURRENCY);
134    }
135    auto_max_concurrency()
136}
137
138/// Auto permits from CPUs and free RAM (50% free-RAM safety margin).
139pub fn auto_max_concurrency() -> usize {
140    let cpus = std::thread::available_parallelism()
141        .map(|n| n.get())
142        .unwrap_or(2)
143        .max(1);
144    let ram_based = match free_ram_mib() {
145        Some(free) => {
146            let usable = free / 2; // 50% safety margin on free RAM
147            ((usable / RAM_PER_TASK_MIB).max(1) as usize).max(1)
148        }
149        None => cpus,
150    };
151    cpus.min(ram_based).clamp(1, MAX_AUTO_CONCURRENCY)
152}
153
154/// Worker thread hint for the multi-thread runtime (same as auto concurrency
155/// floor on CPUs, independent of RAM clamp for the blocking pool).
156pub fn runtime_worker_threads() -> usize {
157    std::thread::available_parallelism()
158        .map(|n| n.get())
159        .unwrap_or(2)
160        .clamp(1, MAX_AUTO_CONCURRENCY)
161}
162
163/// Linux `MemAvailable` in MiB; `None` when unavailable.
164fn free_ram_mib() -> Option<u64> {
165    #[cfg(target_os = "linux")]
166    {
167        let text = fs::read_to_string("/proc/meminfo").ok()?;
168        for line in text.lines() {
169            if let Some(rest) = line.strip_prefix("MemAvailable:") {
170                let kb: u64 = rest
171                    .split_whitespace()
172                    .next()?
173                    .parse()
174                    .ok()?;
175                return Some(kb / 1024);
176            }
177        }
178        None
179    }
180    #[cfg(not(target_os = "linux"))]
181    {
182        let _ = fs::metadata;
183        None
184    }
185}
186
187#[cfg(test)]
188mod tests {
189    use super::*;
190
191    #[test]
192    fn configured_override_respected() {
193        assert_eq!(resolve_max_concurrency(4), 4);
194        assert_eq!(resolve_max_concurrency(1), 1);
195    }
196
197    #[test]
198    fn auto_is_at_least_one() {
199        assert!(auto_max_concurrency() >= 1);
200        assert!(auto_max_concurrency() <= MAX_AUTO_CONCURRENCY);
201    }
202
203    #[test]
204    fn budget_reports_max_and_available() {
205        let b = ConcurrencyBudget::new(3);
206        assert_eq!(b.max(), 3);
207        assert_eq!(b.available_permits(), 3);
208    }
209
210    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
211    async fn run_cpu_bound_returns_value_and_releases_permit() {
212        let b = ConcurrencyBudget::new(2);
213        let out = b
214            .run_cpu_bound(|| Ok::<_, AppError>(41 + 1))
215            .await
216            .unwrap();
217        assert_eq!(out, 42);
218        assert_eq!(b.available_permits(), 2);
219    }
220
221    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
222    async fn run_cpu_bound_propagates_closure_error() {
223        let b = ConcurrencyBudget::new(1);
224        let err = b
225            .run_cpu_bound(|| -> AppResult<()> {
226                Err(AppError::new(
227                    ErrorKind::Parse,
228                    "synthetic parse failure",
229                ))
230            })
231            .await
232            .unwrap_err();
233        assert_eq!(err.kind(), ErrorKind::Parse);
234        assert_eq!(b.available_permits(), 1);
235    }
236
237    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
238    async fn peak_concurrency_never_exceeds_max() {
239        use std::sync::atomic::{AtomicUsize, Ordering};
240        let b = ConcurrencyBudget::new(2);
241        let peak = Arc::new(AtomicUsize::new(0));
242        let current = Arc::new(AtomicUsize::new(0));
243        let mut handles = Vec::new();
244        for _ in 0..8 {
245            let b = b.clone();
246            let peak = Arc::clone(&peak);
247            let current = Arc::clone(&current);
248            handles.push(tokio::spawn(async move {
249                b.run_cpu_bound(move || {
250                    let now = current.fetch_add(1, Ordering::SeqCst) + 1;
251                    peak.fetch_max(now, Ordering::SeqCst);
252                    std::thread::sleep(std::time::Duration::from_millis(15));
253                    current.fetch_sub(1, Ordering::SeqCst);
254                    Ok::<_, AppError>(())
255                })
256                .await
257            }));
258        }
259        for h in handles {
260            h.await.unwrap().unwrap();
261        }
262        assert!(
263            peak.load(Ordering::SeqCst) <= 2,
264            "peak {} exceeded budget 2",
265            peak.load(Ordering::SeqCst)
266        );
267        assert_eq!(b.available_permits(), 2);
268    }
269}