docsrs_cli/
concurrency.rs1use std::fs;
24use std::sync::Arc;
25
26use tokio::sync::{OwnedSemaphorePermit, Semaphore};
27
28use crate::error::{AppError, AppResult, ErrorDetail, InternalOp};
29
30pub const RAM_PER_TASK_MIB: u64 = 48;
36
37pub const MAX_AUTO_CONCURRENCY: usize = 32;
39
40pub const MAX_EXPLICIT_CONCURRENCY: usize = 256;
42
43#[derive(Debug, Clone)]
45pub struct ConcurrencyBudget {
46 max: usize,
47 semaphore: Arc<Semaphore>,
48}
49
50impl ConcurrencyBudget {
51 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 pub fn from_configured(configured: u32) -> Self {
63 Self::new(resolve_max_concurrency(configured))
64 }
65
66 pub fn max(&self) -> usize {
68 self.max
69 }
70
71 pub fn available_permits(&self) -> usize {
73 self.semaphore.available_permits()
74 }
75
76 pub fn semaphore(&self) -> Arc<Semaphore> {
78 Arc::clone(&self.semaphore)
79 }
80
81 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 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
137pub 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
149pub 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; ((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
165pub 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
177pub fn max_blocking_threads() -> usize {
183 MAX_EXPLICIT_CONCURRENCY
184}
185
186const LINUX_MEMINFO_PATH: &str = "/proc/meminfo";
188
189const MEM_AVAILABLE_PREFIX: &str = "MemAvailable:";
191
192const KIB_PER_MIB: u64 = 1024;
194
195fn 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
210fn 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 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 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 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(¤t);
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}