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> {
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 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
134pub 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
146pub 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; ((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
162pub 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
174pub fn max_blocking_threads() -> usize {
180 MAX_EXPLICIT_CONCURRENCY
181}
182
183fn 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(¤t);
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}