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` or `max_concurrency` in XDG
21//!   `config.toml` only (not product `DOCSRS_CLI_*` env). `0` / omit = auto.
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    ///
83    /// # Errors
84    ///
85    /// Returns [`ErrorKind::Internal`] when the semaphore is closed (should not
86    /// happen in the one-shot lifecycle). The `AcquireError` is preserved as
87    /// [`std::error::Error::source`].
88    pub async fn acquire_owned(&self) -> AppResult<OwnedSemaphorePermit> {
89        self.semaphore
90            .clone()
91            .acquire_owned()
92            .await
93            .map_err(|e| {
94                AppError::with_source(ErrorKind::Internal, "concurrency semaphore closed", e)
95            })
96    }
97
98    /// Run CPU / blocking work on Tokio's blocking pool under this budget.
99    ///
100    /// Acquires a permit before `spawn_blocking`; the permit is held until the
101    /// closure returns (dropped inside the blocking thread).
102    ///
103    /// # Errors
104    ///
105    /// Propagates closure errors. Maps worker panic to [`ErrorKind::Internal`]
106    /// and abort/cancel to [`ErrorKind::Interrupted`].
107    pub async fn run_cpu_bound<F, T>(&self, f: F) -> AppResult<T>
108    where
109        F: FnOnce() -> AppResult<T> + Send + 'static,
110        T: Send + 'static,
111    {
112        let permit = self.acquire_owned().await?;
113        let join = tokio::task::spawn_blocking(move || {
114            let _permit = permit;
115            f()
116        });
117        match join.await {
118            Ok(inner) => inner,
119            Err(e) if e.is_cancelled() => Err(AppError::interrupted()),
120            Err(e) if e.is_panic() => Err(AppError::with_source(
121                ErrorKind::Internal,
122                "cpu worker panicked during parse",
123                e,
124            )),
125            Err(e) => Err(AppError::with_source(
126                ErrorKind::Internal,
127                "cpu worker join failed",
128                e,
129            )),
130        }
131    }
132}
133
134/// Resolve permit count from config override (`0` = auto).
135///
136/// Auto formula (documented at module root):
137/// `min(cpus, max(1, (free_ram_mib / 2) / RAM_PER_TASK_MIB))` then clamp
138/// to `[1, MAX_AUTO_CONCURRENCY]`.
139pub fn resolve_max_concurrency(configured: u32) -> usize {
140    if configured > 0 {
141        return (configured as usize).clamp(1, MAX_EXPLICIT_CONCURRENCY);
142    }
143    auto_max_concurrency()
144}
145
146/// Auto permits from CPUs and free RAM (50% free-RAM safety margin).
147pub fn auto_max_concurrency() -> usize {
148    let cpus = std::thread::available_parallelism()
149        .map(|n| n.get())
150        .unwrap_or(2)
151        .max(1);
152    let ram_based = match free_ram_mib() {
153        Some(free) => {
154            let usable = free / 2; // 50% safety margin on free RAM
155            ((usable / RAM_PER_TASK_MIB).max(1) as usize).max(1)
156        }
157        None => cpus,
158    };
159    cpus.min(ram_based).clamp(1, MAX_AUTO_CONCURRENCY)
160}
161
162/// Worker thread count for the multi-thread Tokio runtime (I/O + signal tasks).
163///
164/// Same floor as auto concurrency on CPUs, independent of the RAM clamp used for
165/// the CPU budget (I/O workers stay available while blocking parse runs).
166/// Used by `src/main.rs` `Builder::worker_threads`.
167pub fn runtime_worker_threads() -> usize {
168    std::thread::available_parallelism()
169        .map(|n| n.get())
170        .unwrap_or(2)
171        .clamp(1, MAX_AUTO_CONCURRENCY)
172}
173
174/// Cap for Tokio's `spawn_blocking` pool (Rules Rust — rede / paralelismo).
175///
176/// Aligns with [`MAX_EXPLICIT_CONCURRENCY`] so an operator override cannot
177/// schedule more blocking tasks than the product ever admits via
178/// [`ConcurrencyBudget`]. Default Tokio (512) is far above one-shot CLI needs.
179pub fn max_blocking_threads() -> usize {
180    MAX_EXPLICIT_CONCURRENCY
181}
182
183/// Linux `MemAvailable` in MiB; `None` when unavailable.
184fn free_ram_mib() -> Option<u64> {
185    #[cfg(target_os = "linux")]
186    {
187        let text = fs::read_to_string("/proc/meminfo").ok()?;
188        for line in text.lines() {
189            if let Some(rest) = line.strip_prefix("MemAvailable:") {
190                let kb: u64 = rest.split_whitespace().next()?.parse().ok()?;
191                return Some(kb / 1024);
192            }
193        }
194        None
195    }
196    #[cfg(not(target_os = "linux"))]
197    {
198        let _ = fs::metadata;
199        None
200    }
201}
202
203#[cfg(test)]
204mod tests {
205    use super::*;
206
207    #[test]
208    fn configured_override_respected() {
209        assert_eq!(resolve_max_concurrency(4), 4);
210        assert_eq!(resolve_max_concurrency(1), 1);
211    }
212
213    #[test]
214    fn auto_is_at_least_one() {
215        assert!(auto_max_concurrency() >= 1);
216        assert!(auto_max_concurrency() <= MAX_AUTO_CONCURRENCY);
217    }
218
219    #[test]
220    fn runtime_and_blocking_pool_caps_are_bounded() {
221        let w = runtime_worker_threads();
222        assert!((1..=MAX_AUTO_CONCURRENCY).contains(&w));
223        assert_eq!(max_blocking_threads(), MAX_EXPLICIT_CONCURRENCY);
224    }
225
226    #[test]
227    fn budget_reports_max_and_available() {
228        let b = ConcurrencyBudget::new(3);
229        assert_eq!(b.max(), 3);
230        assert_eq!(b.available_permits(), 3);
231    }
232
233    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
234    async fn run_cpu_bound_returns_value_and_releases_permit() {
235        let b = ConcurrencyBudget::new(2);
236        let out = b.run_cpu_bound(|| Ok::<_, AppError>(41 + 1)).await.unwrap();
237        assert_eq!(out, 42);
238        assert_eq!(b.available_permits(), 2);
239    }
240
241    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
242    async fn run_cpu_bound_propagates_closure_error() {
243        let b = ConcurrencyBudget::new(1);
244        let err = b
245            .run_cpu_bound(|| -> AppResult<()> {
246                Err(AppError::new(ErrorKind::Parse, "synthetic parse failure"))
247            })
248            .await
249            .unwrap_err();
250        assert_eq!(err.kind(), ErrorKind::Parse);
251        assert_eq!(b.available_permits(), 1);
252    }
253
254    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
255    async fn peak_concurrency_never_exceeds_max() {
256        use std::sync::atomic::{AtomicUsize, Ordering};
257        let b = ConcurrencyBudget::new(2);
258        let peak = Arc::new(AtomicUsize::new(0));
259        let current = Arc::new(AtomicUsize::new(0));
260        let mut handles = Vec::new();
261        for _ in 0..8 {
262            let b = b.clone();
263            let peak = Arc::clone(&peak);
264            let current = Arc::clone(&current);
265            handles.push(tokio::spawn(async move {
266                b.run_cpu_bound(move || {
267                    let now = current.fetch_add(1, Ordering::SeqCst) + 1;
268                    peak.fetch_max(now, Ordering::SeqCst);
269                    std::thread::sleep(std::time::Duration::from_millis(15));
270                    current.fetch_sub(1, Ordering::SeqCst);
271                    Ok::<_, AppError>(())
272                })
273                .await
274            }));
275        }
276        for h in handles {
277            h.await.unwrap().unwrap();
278        }
279        assert!(
280            peak.load(Ordering::SeqCst) <= 2,
281            "peak {} exceeded budget 2",
282            peak.load(Ordering::SeqCst)
283        );
284        assert_eq!(b.available_permits(), 2);
285    }
286}