docsrs_cli/
concurrency.rs1use std::fs;
24use std::sync::Arc;
25
26use tokio::sync::{OwnedSemaphorePermit, Semaphore};
27
28use crate::error::{AppError, AppResult, ErrorKind};
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> {
83 self.semaphore
84 .clone()
85 .acquire_owned()
86 .await
87 .map_err(|_| AppError::new(ErrorKind::Internal, "concurrency semaphore closed"))
88 }
89
90 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
126pub 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
138pub 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; ((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
154pub 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
163fn 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.split_whitespace().next()?.parse().ok()?;
171 return Some(kb / 1024);
172 }
173 }
174 None
175 }
176 #[cfg(not(target_os = "linux"))]
177 {
178 let _ = fs::metadata;
179 None
180 }
181}
182
183#[cfg(test)]
184mod tests {
185 use super::*;
186
187 #[test]
188 fn configured_override_respected() {
189 assert_eq!(resolve_max_concurrency(4), 4);
190 assert_eq!(resolve_max_concurrency(1), 1);
191 }
192
193 #[test]
194 fn auto_is_at_least_one() {
195 assert!(auto_max_concurrency() >= 1);
196 assert!(auto_max_concurrency() <= MAX_AUTO_CONCURRENCY);
197 }
198
199 #[test]
200 fn budget_reports_max_and_available() {
201 let b = ConcurrencyBudget::new(3);
202 assert_eq!(b.max(), 3);
203 assert_eq!(b.available_permits(), 3);
204 }
205
206 #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
207 async fn run_cpu_bound_returns_value_and_releases_permit() {
208 let b = ConcurrencyBudget::new(2);
209 let out = b.run_cpu_bound(|| Ok::<_, AppError>(41 + 1)).await.unwrap();
210 assert_eq!(out, 42);
211 assert_eq!(b.available_permits(), 2);
212 }
213
214 #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
215 async fn run_cpu_bound_propagates_closure_error() {
216 let b = ConcurrencyBudget::new(1);
217 let err = b
218 .run_cpu_bound(|| -> AppResult<()> {
219 Err(AppError::new(ErrorKind::Parse, "synthetic parse failure"))
220 })
221 .await
222 .unwrap_err();
223 assert_eq!(err.kind(), ErrorKind::Parse);
224 assert_eq!(b.available_permits(), 1);
225 }
226
227 #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
228 async fn peak_concurrency_never_exceeds_max() {
229 use std::sync::atomic::{AtomicUsize, Ordering};
230 let b = ConcurrencyBudget::new(2);
231 let peak = Arc::new(AtomicUsize::new(0));
232 let current = Arc::new(AtomicUsize::new(0));
233 let mut handles = Vec::new();
234 for _ in 0..8 {
235 let b = b.clone();
236 let peak = Arc::clone(&peak);
237 let current = Arc::clone(¤t);
238 handles.push(tokio::spawn(async move {
239 b.run_cpu_bound(move || {
240 let now = current.fetch_add(1, Ordering::SeqCst) + 1;
241 peak.fetch_max(now, Ordering::SeqCst);
242 std::thread::sleep(std::time::Duration::from_millis(15));
243 current.fetch_sub(1, Ordering::SeqCst);
244 Ok::<_, AppError>(())
245 })
246 .await
247 }));
248 }
249 for h in handles {
250 h.await.unwrap().unwrap();
251 }
252 assert!(
253 peak.load(Ordering::SeqCst) <= 2,
254 "peak {} exceeded budget 2",
255 peak.load(Ordering::SeqCst)
256 );
257 assert_eq!(b.available_permits(), 2);
258 }
259}