1use std::{
12 collections::HashMap,
13 fmt,
14 panic::{catch_unwind, AssertUnwindSafe},
15 sync::{Arc, Mutex},
16 time::Duration,
17};
18
19use tokio::{
20 sync::{OwnedSemaphorePermit, Semaphore},
21 time::Instant,
22};
23use tokio_util::sync::CancellationToken;
24
25use crate::{ModuleHandle, RequestKey, DISPATCH_SATURATION_WAIT, HANDLER_TASK_CAPACITY};
26
27pub(crate) const PERMIT_WAIT_WARNING: Duration = Duration::from_secs(2);
31
32#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
34#[non_exhaustive]
35pub enum RequestPool {
36 Default,
39 LongHeld,
42}
43
44impl RequestPool {
45 pub fn name(self) -> &'static str {
47 match self {
48 Self::Default => "default",
49 Self::LongHeld => "long_held",
50 }
51 }
52}
53
54impl fmt::Display for RequestPool {
55 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
56 f.write_str(self.name())
57 }
58}
59
60#[derive(Debug, Clone, Copy, PartialEq, Eq)]
63#[non_exhaustive]
64pub struct RequestClass {
65 pub pool: RequestPool,
66 pub op: Option<&'static str>,
69}
70
71impl RequestClass {
72 pub const fn default_pool() -> Self {
74 Self {
75 pool: RequestPool::Default,
76 op: None,
77 }
78 }
79
80 pub const fn long_held() -> Self {
82 Self {
83 pool: RequestPool::LongHeld,
84 op: None,
85 }
86 }
87
88 pub const fn with_op(mut self, op: &'static str) -> Self {
90 self.op = Some(op);
91 self
92 }
93}
94
95impl Default for RequestClass {
96 fn default() -> Self {
97 Self::default_pool()
98 }
99}
100
101type Classifier = dyn Fn(&[u8]) -> RequestClass + Send + Sync;
102
103#[derive(Clone, Default)]
111#[non_exhaustive]
112pub struct RequestPools {
113 long_held: Option<(usize, Arc<Classifier>)>,
114}
115
116impl RequestPools {
117 pub fn new() -> Self {
119 Self::default()
120 }
121
122 pub fn with_long_held<F>(mut self, limit: usize, classifier: F) -> Self
137 where
138 F: Fn(&[u8]) -> RequestClass + Send + Sync + 'static,
139 {
140 self.long_held = Some((limit.max(1), Arc::new(classifier)));
141 self
142 }
143
144 pub fn long_held_limit(&self) -> Option<usize> {
147 self.long_held.as_ref().map(|(limit, _)| *limit)
148 }
149}
150
151impl fmt::Debug for RequestPools {
152 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
153 f.debug_struct("RequestPools")
154 .field("long_held_limit", &self.long_held_limit())
155 .finish_non_exhaustive()
156 }
157}
158
159#[derive(Debug, Clone, PartialEq, Eq)]
162#[non_exhaustive]
163pub struct RequestPoolSnapshot {
164 pub pool: RequestPool,
165 pub in_use: usize,
167 pub limit: usize,
169 pub waiting: usize,
171 pub oldest_wait: Option<Duration>,
174}
175
176type WaitingRequests = Arc<Mutex<HashMap<RequestKey, Instant>>>;
177
178#[derive(Clone)]
181pub(crate) struct PermitPool {
182 pub(crate) pool: RequestPool,
183 pub(crate) limit: usize,
184 pub(crate) permits: Arc<Semaphore>,
185 pub(crate) waiting: WaitingRequests,
191}
192
193impl PermitPool {
194 pub(crate) fn new(pool: RequestPool, limit: usize) -> Self {
195 Self {
196 pool,
197 limit,
198 permits: Arc::new(Semaphore::new(limit)),
199 waiting: Arc::new(Mutex::new(HashMap::new())),
200 }
201 }
202
203 fn in_use(&self) -> usize {
204 self.limit.saturating_sub(self.permits.available_permits())
205 }
206
207 fn lock_waiting(&self) -> std::sync::MutexGuard<'_, HashMap<RequestKey, Instant>> {
208 self.waiting
209 .lock()
210 .unwrap_or_else(|poisoned| poisoned.into_inner())
211 }
212
213 pub(crate) fn start_waiting(&self, key: RequestKey) -> PermitWait {
216 let since = Instant::now();
217 self.lock_waiting().insert(key, since);
218 PermitWait {
219 waiting: Arc::clone(&self.waiting),
220 key,
221 since,
222 }
223 }
224
225 pub(crate) fn snapshot(&self) -> RequestPoolSnapshot {
226 let waiting = self.lock_waiting();
227 let oldest_wait = waiting.values().min().map(Instant::elapsed);
228 let count = waiting.len();
229 drop(waiting);
230 RequestPoolSnapshot {
231 pool: self.pool,
232 in_use: self.in_use(),
233 limit: self.limit,
234 waiting: count,
235 oldest_wait,
236 }
237 }
238
239 fn saturation(&self, named: bool) -> Option<String> {
244 let snapshot = self.snapshot();
245 let age = snapshot.oldest_wait.filter(|age| {
246 self.permits.available_permits() == 0 && *age > DISPATCH_SATURATION_WAIT
247 })?;
248 let pool = if named {
249 format!(" in the {} pool", self.pool.name())
250 } else {
251 String::new()
252 };
253 Some(format!(
254 "request dispatch saturated{pool}: {}/{} in use, oldest waiting {:.1} s",
255 snapshot.in_use,
256 snapshot.limit,
257 age.as_secs_f64(),
258 ))
259 }
260}
261
262pub(crate) struct PermitWait {
266 waiting: WaitingRequests,
267 key: RequestKey,
268 since: Instant,
269}
270
271impl Drop for PermitWait {
272 fn drop(&mut self) {
273 self.waiting
274 .lock()
275 .unwrap_or_else(|poisoned| poisoned.into_inner())
276 .remove(&self.key);
277 }
278}
279
280pub(crate) struct DispatchPools {
282 pub(crate) default: PermitPool,
283 pub(crate) long_held: Option<(PermitPool, Arc<Classifier>)>,
285}
286
287impl DispatchPools {
288 pub(crate) fn new(config: RequestPools) -> Self {
289 Self::with_default_limit(HANDLER_TASK_CAPACITY, config)
290 }
291
292 pub(crate) fn with_default_limit(default_limit: usize, config: RequestPools) -> Self {
293 Self {
294 default: PermitPool::new(RequestPool::Default, default_limit),
295 long_held: config.long_held.map(|(limit, classifier)| {
296 (PermitPool::new(RequestPool::LongHeld, limit), classifier)
297 }),
298 }
299 }
300
301 pub(crate) fn pools(&self) -> impl Iterator<Item = &PermitPool> {
303 std::iter::once(&self.default).chain(self.long_held.as_ref().map(|(pool, _)| pool))
304 }
305
306 pub(crate) fn classify(&self, body: &[u8]) -> (&PermitPool, Option<&'static str>) {
309 let Some((long_held, classifier)) = &self.long_held else {
310 return (&self.default, None);
311 };
312 let class = match catch_unwind(AssertUnwindSafe(|| classifier(body))) {
313 Ok(class) => class,
314 Err(_) => {
315 tracing::warn!(
316 "the module's request classifier panicked; the request uses the default pool"
317 );
318 RequestClass::default_pool()
319 }
320 };
321 let pool = match class.pool {
322 RequestPool::LongHeld => long_held,
323 RequestPool::Default => &self.default,
324 };
325 (pool, class.op)
326 }
327
328 pub(crate) fn saturation(&self) -> Option<String> {
332 let named = self.long_held.is_some();
333 let sentences = self
334 .pools()
335 .filter_map(|pool| pool.saturation(named))
336 .collect::<Vec<_>>();
337 (!sentences.is_empty()).then(|| sentences.join("; "))
338 }
339
340 pub(crate) fn snapshots(&self) -> Vec<RequestPoolSnapshot> {
341 self.pools().map(PermitPool::snapshot).collect()
342 }
343
344 pub(crate) fn close(&self) {
346 for pool in self.pools() {
347 pool.permits.close();
348 }
349 }
350}
351
352pub(crate) enum PermitWaitOutcome {
354 Acquired(OwnedSemaphorePermit),
355 Cancelled,
357 Closed,
359}
360
361pub(crate) struct WaitingRequest {
363 pub(crate) op: Option<&'static str>,
364 pub(crate) channel: u16,
365 pub(crate) corr: u64,
366}
367
368pub(crate) async fn wait_for_permit(
373 pool: &PermitPool,
374 wait: PermitWait,
375 request: WaitingRequest,
376 cancelled: &CancellationToken,
377) -> PermitWaitOutcome {
378 let acquire = Arc::clone(&pool.permits).acquire_owned();
379 let warn_at = tokio::time::sleep_until(wait.since + PERMIT_WAIT_WARNING);
380 tokio::pin!(acquire, warn_at);
381 let mut warned = false;
382 let outcome = loop {
383 tokio::select! {
384 biased;
389 permit = &mut acquire => {
390 break match permit {
391 Ok(permit) => PermitWaitOutcome::Acquired(permit),
392 Err(_) => PermitWaitOutcome::Closed,
393 };
394 }
395 () = cancelled.cancelled() => break PermitWaitOutcome::Cancelled,
396 () = &mut warn_at, if !warned => {
399 warned = true;
400 tracing::warn!(
401 op = request.op.unwrap_or("<none>"),
402 pool = pool.pool.name(),
403 in_use = pool.in_use(),
404 limit = pool.limit,
405 channel = request.channel,
406 corr = request.corr,
407 waited_ms = u64::try_from(wait.since.elapsed().as_millis()).unwrap_or(u64::MAX),
408 "data request is still waiting for a handler slot after {} s",
409 PERMIT_WAIT_WARNING.as_secs(),
410 );
411 }
412 }
413 };
414 drop(wait);
415 outcome
416}
417
418impl ModuleHandle {
419 pub fn request_pool_snapshots(&self) -> Vec<RequestPoolSnapshot> {
423 self.dispatch_pools().snapshots()
424 }
425
426 pub(crate) fn install_dispatch_pools(&self, config: RequestPools) {
429 *self
430 .shared
431 .dispatch_pools
432 .lock()
433 .unwrap_or_else(|poisoned| poisoned.into_inner()) =
434 Arc::new(DispatchPools::new(config));
435 }
436
437 pub(crate) fn dispatch_pools(&self) -> Arc<DispatchPools> {
438 Arc::clone(
439 &self
440 .shared
441 .dispatch_pools
442 .lock()
443 .unwrap_or_else(|poisoned| poisoned.into_inner()),
444 )
445 }
446}