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