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, ErrorDetail, InternalOp};
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 [`crate::error::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.clone().acquire_owned().await.map_err(|e| {
90            AppError::of_with_source(
91                ErrorDetail::Internal {
92                    op: InternalOp::SemaphoreClosed,
93                },
94                e,
95            )
96        })
97    }
98
99    /// Run CPU / blocking work on Tokio's blocking pool under this budget.
100    ///
101    /// Acquires a permit before `spawn_blocking`; the permit is held until the
102    /// closure returns (dropped inside the blocking thread).
103    ///
104    /// # Errors
105    ///
106    /// Propagates closure errors. Maps worker panic to [`crate::error::ErrorKind::Internal`]
107    /// and abort/cancel to [`crate::error::ErrorKind::Interrupted`].
108    pub async fn run_cpu_bound<F, T>(&self, f: F) -> AppResult<T>
109    where
110        F: FnOnce() -> AppResult<T> + Send + 'static,
111        T: Send + 'static,
112    {
113        let permit = self.acquire_owned().await?;
114        let join = tokio::task::spawn_blocking(move || {
115            let _permit = permit;
116            f()
117        });
118        match join.await {
119            Ok(inner) => inner,
120            Err(e) if e.is_cancelled() => Err(AppError::interrupted()),
121            Err(e) if e.is_panic() => Err(AppError::of_with_source(
122                ErrorDetail::Internal {
123                    op: InternalOp::WorkerPanic,
124                },
125                e,
126            )),
127            Err(e) => Err(AppError::of_with_source(
128                ErrorDetail::Internal {
129                    op: InternalOp::WorkerJoin,
130                },
131                e,
132            )),
133        }
134    }
135}
136
137/// Resolve permit count from config override (`0` = auto).
138///
139/// Auto formula (documented at module root):
140/// `min(cpus, max(1, (free_ram_mib / 2) / RAM_PER_TASK_MIB))` then clamp
141/// to `[1, MAX_AUTO_CONCURRENCY]`.
142pub fn resolve_max_concurrency(configured: u32) -> usize {
143    if configured > 0 {
144        return (configured as usize).clamp(1, MAX_EXPLICIT_CONCURRENCY);
145    }
146    auto_max_concurrency()
147}
148
149/// Auto permits from CPUs and free RAM (50% free-RAM safety margin).
150pub fn auto_max_concurrency() -> usize {
151    let cpus = std::thread::available_parallelism()
152        .map(|n| n.get())
153        .unwrap_or(2)
154        .max(1);
155    let ram_based = match free_ram_mib() {
156        Some(free) => {
157            let usable = free / 2; // 50% safety margin on free RAM
158            ((usable / RAM_PER_TASK_MIB).max(1) as usize).max(1)
159        }
160        None => cpus,
161    };
162    cpus.min(ram_based).clamp(1, MAX_AUTO_CONCURRENCY)
163}
164
165/// Worker thread count for the multi-thread Tokio runtime (I/O + signal tasks).
166///
167/// Same floor as auto concurrency on CPUs, independent of the RAM clamp used for
168/// the CPU budget (I/O workers stay available while blocking parse runs).
169/// Used by `src/main.rs` `Builder::worker_threads`.
170pub fn runtime_worker_threads() -> usize {
171    std::thread::available_parallelism()
172        .map(|n| n.get())
173        .unwrap_or(2)
174        .clamp(1, MAX_AUTO_CONCURRENCY)
175}
176
177/// Cap for Tokio's `spawn_blocking` pool (Rules Rust — rede / paralelismo).
178///
179/// Aligns with [`MAX_EXPLICIT_CONCURRENCY`] so an operator override cannot
180/// schedule more blocking tasks than the product ever admits via
181/// [`ConcurrencyBudget`]. Default Tokio (512) is far above one-shot CLI needs.
182pub fn max_blocking_threads() -> usize {
183    MAX_EXPLICIT_CONCURRENCY
184}
185
186/// Path exposing kernel memory counters on Linux.
187const LINUX_MEMINFO_PATH: &str = "/proc/meminfo";
188
189/// `/proc/meminfo` field prefix carrying available memory in KiB.
190const MEM_AVAILABLE_PREFIX: &str = "MemAvailable:";
191
192/// KiB per MiB, used to convert the `/proc/meminfo` unit.
193const KIB_PER_MIB: u64 = 1024;
194
195/// Linux `MemAvailable` in MiB; `None` on other platforms or on parse failure.
196///
197/// Uses a runtime [`cfg!`] guard instead of a `#[cfg]` attribute so the whole
198/// body is type-checked on every target from a single host build. Attribute
199/// `cfg` is resolved during macro expansion, before type checking, which lets
200/// a non-host branch reach a release unverified. The comparison is a compile-
201/// time constant, so the branch is folded away and costs nothing at runtime.
202fn free_ram_mib() -> Option<u64> {
203    if !cfg!(target_os = "linux") {
204        return None;
205    }
206    let text = fs::read_to_string(LINUX_MEMINFO_PATH).ok()?;
207    parse_mem_available_mib(&text)
208}
209
210/// Parses `MemAvailable` from `/proc/meminfo` contents, in MiB.
211///
212/// Pure and platform-agnostic so it stays unit-testable on every target.
213/// Returns `None` when the field is absent, empty, or not a base-10 integer.
214fn parse_mem_available_mib(text: &str) -> Option<u64> {
215    for line in text.lines() {
216        if let Some(rest) = line.strip_prefix(MEM_AVAILABLE_PREFIX) {
217            let kib: u64 = rest.split_whitespace().next()?.parse().ok()?;
218            return Some(kib / KIB_PER_MIB);
219        }
220    }
221    None
222}
223
224#[cfg(test)]
225mod tests {
226    use super::*;
227    use crate::error::ErrorKind;
228
229    /// Realistic `/proc/meminfo` head: only `MemAvailable` must be read.
230    const MEMINFO_SAMPLE: &str = "MemTotal:       16341234 kB\nMemFree:         1234567 kB\nMemAvailable:    8388608 kB\nBuffers:          123456 kB\n";
231
232    #[test]
233    fn parses_mem_available_into_mib() {
234        // 8388608 KiB / 1024 = 8192 MiB
235        assert_eq!(parse_mem_available_mib(MEMINFO_SAMPLE), Some(8192));
236    }
237
238    #[test]
239    fn missing_field_yields_none() {
240        let text = "MemTotal:       16341234 kB\nMemFree:         1234567 kB\n";
241        assert_eq!(parse_mem_available_mib(text), None);
242    }
243
244    #[test]
245    fn non_numeric_value_yields_none() {
246        assert_eq!(
247            parse_mem_available_mib("MemAvailable:    not-a-number kB\n"),
248            None
249        );
250    }
251
252    #[test]
253    fn truncated_line_without_value_yields_none() {
254        assert_eq!(parse_mem_available_mib("MemAvailable:\n"), None);
255    }
256
257    #[test]
258    fn empty_input_yields_none() {
259        assert_eq!(parse_mem_available_mib(""), None);
260    }
261
262    #[test]
263    fn free_ram_is_none_or_positive_on_every_platform() {
264        // Runtime cfg! guard keeps this callable (and type-checked) everywhere.
265        if let Some(mib) = free_ram_mib() {
266            assert!(mib > 0, "MemAvailable reported {mib} MiB");
267        }
268    }
269
270    #[test]
271    fn configured_override_respected() {
272        assert_eq!(resolve_max_concurrency(4), 4);
273        assert_eq!(resolve_max_concurrency(1), 1);
274    }
275
276    #[test]
277    fn auto_is_at_least_one() {
278        assert!(auto_max_concurrency() >= 1);
279        assert!(auto_max_concurrency() <= MAX_AUTO_CONCURRENCY);
280    }
281
282    #[test]
283    fn runtime_and_blocking_pool_caps_are_bounded() {
284        let w = runtime_worker_threads();
285        assert!((1..=MAX_AUTO_CONCURRENCY).contains(&w));
286        assert_eq!(max_blocking_threads(), MAX_EXPLICIT_CONCURRENCY);
287    }
288
289    #[test]
290    fn budget_reports_max_and_available() {
291        let b = ConcurrencyBudget::new(3);
292        assert_eq!(b.max(), 3);
293        assert_eq!(b.available_permits(), 3);
294    }
295
296    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
297    async fn run_cpu_bound_returns_value_and_releases_permit() {
298        let b = ConcurrencyBudget::new(2);
299        let out = b.run_cpu_bound(|| Ok::<_, AppError>(41 + 1)).await.unwrap();
300        assert_eq!(out, 42);
301        assert_eq!(b.available_permits(), 2);
302    }
303
304    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
305    async fn run_cpu_bound_propagates_closure_error() {
306        let b = ConcurrencyBudget::new(1);
307        let err = b
308            .run_cpu_bound(|| -> AppResult<()> {
309                Err(AppError::of(ErrorDetail::Internal {
310                    op: InternalOp::SyntheticParseFailure,
311                }))
312            })
313            .await
314            .unwrap_err();
315        assert_eq!(err.kind(), ErrorKind::Parse);
316        assert_eq!(b.available_permits(), 1);
317    }
318
319    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
320    async fn peak_concurrency_never_exceeds_max() {
321        use std::sync::atomic::{AtomicUsize, Ordering};
322        let b = ConcurrencyBudget::new(2);
323        let peak = Arc::new(AtomicUsize::new(0));
324        let current = Arc::new(AtomicUsize::new(0));
325        let mut handles = Vec::new();
326        for _ in 0..8 {
327            let b = b.clone();
328            let peak = Arc::clone(&peak);
329            let current = Arc::clone(&current);
330            handles.push(tokio::spawn(async move {
331                b.run_cpu_bound(move || {
332                    let now = current.fetch_add(1, Ordering::SeqCst) + 1;
333                    peak.fetch_max(now, Ordering::SeqCst);
334                    std::thread::sleep(std::time::Duration::from_millis(15));
335                    current.fetch_sub(1, Ordering::SeqCst);
336                    Ok::<_, AppError>(())
337                })
338                .await
339            }));
340        }
341        for h in handles {
342            h.await.unwrap().unwrap();
343        }
344        assert!(
345            peak.load(Ordering::SeqCst) <= 2,
346            "peak {} exceeded budget 2",
347            peak.load(Ordering::SeqCst)
348        );
349        assert_eq!(b.available_permits(), 2);
350    }
351}