Skip to main content

objectstore_service/
concurrency.rs

1//! Concurrency limits and task execution helpers.
2//!
3//! [`Limiter`] and [`PriorityLimiter`] provide FIFO and high-priority admission,
4//! with configurable wait timeouts and queue limits. Both return [`Permit`],
5//! which can keep capacity held for a payload stream.
6//!
7//! [`ConcurrencyLimiter`] caps the number of in-flight backend operations
8//! using a tokio semaphore. Each acquired [`ConcurrencyPermit`] notifies
9//! waiters on drop, allowing [`ConcurrencyLimiter::wait_all`] to resolve once
10//! all permits have been returned.
11//!
12//! [`run_metered`] runs an isolated task and waits for its result, while
13//! [`spawn_metered`] starts the same task without waiting. Both provide panic
14//! recovery and `service.task.*` metric emission.
15
16use std::future::Future;
17use std::sync::Arc;
18use std::time::Duration;
19
20use futures_util::FutureExt;
21use sentry::{Hub, SentryFutureExt, TransactionContext};
22use tokio::sync::{AcquireError, Notify, OwnedSemaphorePermit, Semaphore};
23
24use crate::error::{Error, ErrorKind, Panic, Result};
25
26mod limiter;
27
28pub use limiter::{Limiter, LimiterStats, Permit, Priority, PriorityLimiter, PriorityLimiterStats};
29
30/// Interval for the periodic metrics emitter.
31const EMITTER_INTERVAL: Duration = Duration::from_secs(1);
32
33/// Snapshot of concurrency limiter state.
34///
35/// Passed to the callback registered via
36/// [`ConcurrencyLimiter::run_emitter`].
37#[non_exhaustive]
38#[derive(Clone, Copy, Debug)]
39pub struct Stats {
40    /// Number of execution permits currently held.
41    pub in_use: u32,
42    /// Number of callers waiting in the queue for a permit.
43    pub queued: u32,
44    /// Number of bulk operations currently in flight.
45    pub bulk_in_use: u32,
46}
47
48/// Limits concurrent backend operations and tracks in-flight count.
49///
50/// Permits are acquired with [`acquire`](Self::acquire) or
51/// [`acquire_bulk`](Self::acquire_bulk) and automatically returned when
52/// the [`ConcurrencyPermit`] is dropped.
53///
54/// Bulk operations use a separate budget semaphore that limits how many
55/// execution slots they may occupy. This is intended as a safe operating
56/// point — below this level there should be little-to-no performance
57/// degradation, leaving room for more tasks to be admitted via the queue
58/// before rejection is necessary.
59#[derive(Clone, Debug)]
60pub struct ConcurrencyLimiter {
61    tasks: Arc<Semaphore>,
62    queue: Arc<Semaphore>,
63    bulk: Arc<Semaphore>,
64    tasks_total: u32,
65    queue_total: u32,
66    bulk_total: u32,
67    timeout: Duration,
68    released: Arc<Notify>,
69}
70
71impl ConcurrencyLimiter {
72    /// Creates a new limiter with the given maximum number of permits.
73    ///
74    /// By default the queue depth is zero, preserving the original try-or-reject behavior. Use
75    /// [`with_queue`](Self::with_queue) to enable bounded waiting.
76    ///
77    /// The bulk budget defaults to 100% of `max` (no restriction); use
78    /// [`with_bulk`](Self::with_bulk) to set a safe operating point for bulk traffic.
79    pub fn new(max: u32) -> Self {
80        Self {
81            tasks: Arc::new(Semaphore::new(max as usize)),
82            queue: Arc::new(Semaphore::new(0)),
83            bulk: Arc::new(Semaphore::new(max as usize)),
84            tasks_total: max,
85            queue_total: 0,
86            bulk_total: max,
87            timeout: Duration::from_secs(1),
88            released: Arc::new(Notify::new()),
89        }
90    }
91
92    /// Enables bounded waiting when all execution permits are held.
93    ///
94    /// Up to `size` additional callers may park in [`acquire`](Self::acquire)
95    /// waiting for a permit. Callers beyond that are rejected immediately.
96    pub fn with_queue(mut self, size: u32) -> Self {
97        self.queue_total = size;
98        self.queue = Arc::new(Semaphore::new(size as usize));
99        self
100    }
101
102    /// Sets the maximum time a caller may wait for a permit.
103    ///
104    /// Applies to both [`acquire`](Self::acquire) (when parked in the
105    /// queue) and [`acquire_bulk`](Self::acquire_bulk) (waiting for the
106    /// bulk and execution semaphores). Defaults to 1 second.
107    pub fn with_timeout(mut self, timeout: Duration) -> Self {
108        self.timeout = timeout;
109        self
110    }
111
112    /// Sets the bulk concurrency budget as a percentage of `max`.
113    ///
114    /// `percent` is clamped to `1..=100`. At `100` (the default), bulk
115    /// operations can use all execution slots. Lower values set a safe
116    /// operating point below which there is little-to-no performance
117    /// degradation, allowing more tasks to queue before rejection is
118    /// necessary — e.g. `60` means bulk operations can hold at most 60%
119    /// of permits.
120    pub fn with_bulk(mut self, percent: u32) -> Self {
121        let clamped = percent.min(100);
122        self.bulk_total = (self.tasks_total * clamped).div_ceil(100).max(1);
123        self.bulk = Arc::new(Semaphore::new(self.bulk_total as usize));
124        self
125    }
126
127    /// Acquires a single concurrency permit, waiting if necessary.
128    ///
129    /// If a permit is free, returns immediately without touching the
130    /// queue. Otherwise, acquires a queue ticket (bounded by the queue
131    /// depth) and waits up to the configured timeout. Returns
132    /// [`ErrorKind::AtCapacity`] if the queue is full or on timeout.
133    pub async fn acquire(&self) -> Result<ConcurrencyPermit> {
134        if self.tasks_total == 0 {
135            return Err(ErrorKind::AtCapacity.into());
136        }
137
138        // Fast path: Instantly grab a free permit without parking.
139        if let Ok(task_permit) = self.tasks.clone().try_acquire_owned() {
140            return Ok(ConcurrencyPermit {
141                task_permit: Some(task_permit),
142                bulk_permit: None,
143                released: Arc::clone(&self.released),
144            });
145        }
146
147        // Slow path: acquire a temporary queue ticket to bound concurrent
148        // waiters. Released in this scope when the permit is constructed.
149        let _ticket = self
150            .queue
151            .clone()
152            .try_acquire_owned()
153            .map_err(|_| ErrorKind::AtCapacity)?;
154
155        let acquire = self.tasks.clone().acquire_owned();
156        let task_permit = tokio::time::timeout(self.timeout, acquire)
157            .await
158            .map_err(|_| ErrorKind::AtCapacity)?
159            .map_err(|_| ErrorKind::AtCapacity)?;
160
161        Ok(ConcurrencyPermit {
162            task_permit: Some(task_permit),
163            bulk_permit: None,
164            released: Arc::clone(&self.released),
165        })
166    }
167
168    /// Tries to acquire a single permit without waiting.
169    ///
170    /// Returns [`ErrorKind::AtCapacity`] when no permits are available.
171    pub fn try_acquire(&self) -> Result<ConcurrencyPermit> {
172        let task_permit = self
173            .tasks
174            .clone()
175            .try_acquire_owned()
176            .map_err(|_| ErrorKind::AtCapacity)?;
177
178        Ok(ConcurrencyPermit {
179            task_permit: Some(task_permit),
180            bulk_permit: None,
181            released: Arc::clone(&self.released),
182        })
183    }
184
185    /// Acquires a single permit for a bulk operation, waiting if necessary.
186    ///
187    /// Bulk operations are bounded by the bulk budget — a safe operating
188    /// point below which there is little-to-no performance degradation.
189    /// Both the bulk semaphore and the inner execution semaphore are
190    /// acquired under a single timeout deadline configured via
191    /// [`with_timeout`](Self::with_timeout).
192    ///
193    /// Returns [`ErrorKind::AtCapacity`] on timeout or when `max` is zero.
194    pub async fn acquire_bulk(&self) -> Result<ConcurrencyPermit> {
195        if self.tasks_total == 0 {
196            return Err(ErrorKind::AtCapacity.into());
197        }
198
199        let bulk_sem = self.bulk.clone();
200        let tasks_sem = self.tasks.clone();
201
202        let acquire = async move {
203            let bulk_permit = bulk_sem.acquire_owned().await?;
204            let task_permit = tasks_sem.acquire_owned().await?;
205            Ok((task_permit, bulk_permit))
206        };
207
208        let (task_permit, bulk_permit) = tokio::time::timeout(self.timeout, acquire)
209            .await
210            .map_err(|_| ErrorKind::AtCapacity)?
211            .map_err(|_: AcquireError| ErrorKind::AtCapacity)?;
212
213        Ok(ConcurrencyPermit {
214            task_permit: Some(task_permit),
215            bulk_permit: Some(bulk_permit),
216            released: Arc::clone(&self.released),
217        })
218    }
219
220    /// Returns the number of permits currently available.
221    pub fn available_permits(&self) -> u32 {
222        u32::try_from(self.tasks.available_permits()).unwrap_or(self.tasks_total)
223    }
224
225    /// Returns the number of permits currently held.
226    pub fn used_permits(&self) -> u32 {
227        self.tasks_total - self.available_permits()
228    }
229
230    /// Returns the total number of permits.
231    pub fn total_permits(&self) -> u32 {
232        self.tasks_total
233    }
234
235    /// Returns the number of callers currently waiting in the queue.
236    pub fn queued_permits(&self) -> u32 {
237        let available = u32::try_from(self.queue.available_permits()).unwrap_or(self.queue_total);
238        self.queue_total - available
239    }
240
241    /// Returns the configured queue capacity.
242    pub fn total_queue(&self) -> u32 {
243        self.queue_total
244    }
245
246    /// Returns the number of bulk permits currently held.
247    pub fn used_bulk_permits(&self) -> u32 {
248        let available = u32::try_from(self.bulk.available_permits()).unwrap_or(self.bulk_total);
249        self.bulk_total - available
250    }
251
252    /// Returns the bulk concurrency budget.
253    pub fn total_bulk(&self) -> u32 {
254        self.bulk_total
255    }
256
257    /// Waits until all permits have been returned.
258    #[allow(dead_code)]
259    pub async fn wait_all(&self) {
260        loop {
261            let notified = self.released.notified();
262            if self.used_permits() == 0 {
263                return;
264            }
265            notified.await;
266        }
267    }
268
269    /// Returns a snapshot of the current counts.
270    pub fn stats(&self) -> Stats {
271        Stats {
272            in_use: self.used_permits(),
273            queued: self.queued_permits(),
274            bulk_in_use: self.used_bulk_permits(),
275        }
276    }
277
278    /// Periodically calls `emit` with the current in-use and queued counts.
279    ///
280    /// This future runs forever and is intended to be spawned as a background
281    /// task alongside the service.
282    pub async fn run_emitter<F, Fut>(&self, mut emit: F) -> !
283    where
284        F: FnMut(Stats) -> Fut,
285        Fut: Future<Output = ()>,
286    {
287        let mut ticker = tokio::time::interval(EMITTER_INTERVAL);
288        loop {
289            ticker.tick().await;
290            emit(self.stats()).await;
291        }
292    }
293}
294
295/// RAII guard for a concurrency permit.
296///
297/// Dropping this permit releases it back to the [`ConcurrencyLimiter`] and
298/// notifies any task waiting in [`ConcurrencyLimiter::wait_all`].
299///
300/// The execution permit drops before the bulk permit so that a waiter
301/// blocked on the task semaphore sees the freed slot immediately.
302pub struct ConcurrencyPermit {
303    task_permit: Option<OwnedSemaphorePermit>,
304    bulk_permit: Option<OwnedSemaphorePermit>,
305    released: Arc<Notify>,
306}
307
308impl std::fmt::Debug for ConcurrencyPermit {
309    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
310        f.debug_struct("ConcurrencyPermit").finish_non_exhaustive()
311    }
312}
313
314impl Drop for ConcurrencyPermit {
315    fn drop(&mut self) {
316        drop(self.task_permit.take());
317        drop(self.bulk_permit.take());
318        self.released.notify_waiters();
319    }
320}
321
322/// Runs a future on a dedicated task with panic isolation and timing metrics.
323///
324/// The `guard` is moved into the spawned task and dropped after the future
325/// completes, ensuring any resource it represents (e.g. a concurrency permit)
326/// outlives the operation.
327///
328/// Emits `service.task.start` (counter) before spawning and
329/// `service.task.duration` (distribution) when the task completes, both tagged
330/// with the given `operation` name. The duration tag includes an `outcome` of
331/// `"success"` or `"error"`.
332pub async fn run_metered<T, G, F>(operation: &'static str, guard: G, f: F) -> Result<T>
333where
334    T: Send + 'static,
335    G: Send + 'static,
336    F: Future<Output = Result<T>> + Send + 'static,
337{
338    let receiver = spawn_metered_inner(operation, guard, f);
339    receiver.await.map_err(|_| {
340        let error = Error::new(ErrorKind::Internal, "service task dropped");
341        objectstore_log::error!(!!&error, operation, "Task failed");
342        error
343    })?
344}
345
346/// Spawns a metered future without waiting for its result.
347///
348/// The task has the same panic isolation, metrics, and guard lifetime as
349/// [`run_metered`], but its result is discarded.
350pub fn spawn_metered<T, G, F>(operation: &'static str, guard: G, f: F)
351where
352    T: Send + 'static,
353    G: Send + 'static,
354    F: Future<Output = Result<T>> + Send + 'static,
355{
356    drop(spawn_metered_inner(operation, guard, f));
357}
358
359fn spawn_metered_inner<T, G, F>(
360    operation: &'static str,
361    guard: G,
362    f: F,
363) -> tokio::sync::oneshot::Receiver<Result<T>>
364where
365    T: Send + 'static,
366    G: Send + 'static,
367    F: Future<Output = Result<T>> + Send + 'static,
368{
369    objectstore_metrics::count!("service.task.start", operation = operation);
370
371    let hub = Hub::current();
372    let span = hub.configure_scope(|scope| scope.get_span());
373
374    let new_hub = Hub::new_from_top(hub);
375    let transaction = new_hub.start_transaction(TransactionContext::continue_from_span(
376        operation,
377        "tokio.task",
378        span,
379    ));
380
381    let scope_guard = new_hub.push_scope();
382    new_hub.configure_scope(|scope| scope.set_span(Some(transaction.clone().into())));
383
384    let (tx, rx) = tokio::sync::oneshot::channel();
385    tokio::spawn(
386        async move {
387            let start = tokio::time::Instant::now();
388            let result = std::panic::AssertUnwindSafe(f)
389                .catch_unwind()
390                .await
391                .unwrap_or_else(|payload| Err(Panic::new(payload).into()));
392
393            if let Err(ref e) = result {
394                let error = e as &dyn std::error::Error;
395                objectstore_log::event_dyn!(e.level(), error, operation, "Task failed");
396            }
397
398            objectstore_metrics::record!(
399                "service.task.duration" = start.elapsed(),
400                operation = operation,
401                outcome = if result.is_ok() { "success" } else { "error" },
402            );
403
404            let _ = tx.send(result);
405            drop(guard);
406            transaction.finish();
407            drop(scope_guard);
408        }
409        .bind_hub(new_hub),
410    );
411
412    rx
413}
414
415#[cfg(test)]
416mod tests {
417    use std::sync::atomic::{AtomicU32, Ordering};
418
419    use super::*;
420
421    #[test]
422    fn available_permits_tracks_held() {
423        let limiter = ConcurrencyLimiter::new(5);
424        assert_eq!(limiter.available_permits(), 5);
425
426        let p1 = limiter.try_acquire().unwrap();
427        assert_eq!(limiter.available_permits(), 4);
428
429        let p2 = limiter.try_acquire().unwrap();
430        assert_eq!(limiter.available_permits(), 3);
431
432        drop(p1);
433        assert_eq!(limiter.available_permits(), 4);
434
435        drop(p2);
436        assert_eq!(limiter.available_permits(), 5);
437    }
438
439    #[test]
440    fn total_permits_returns_configured_max() {
441        let limiter = ConcurrencyLimiter::new(42);
442        assert_eq!(limiter.total_permits(), 42);
443    }
444
445    #[test]
446    fn acquire_and_release() {
447        let limiter = ConcurrencyLimiter::new(2);
448        assert_eq!(limiter.used_permits(), 0);
449
450        let p1 = limiter.try_acquire().unwrap();
451        assert_eq!(limiter.used_permits(), 1);
452
453        let p2 = limiter.try_acquire().unwrap();
454        assert_eq!(limiter.used_permits(), 2);
455
456        drop(p1);
457        assert_eq!(limiter.used_permits(), 1);
458
459        drop(p2);
460        assert_eq!(limiter.used_permits(), 0);
461    }
462
463    #[test]
464    fn at_capacity_rejects() {
465        let limiter = ConcurrencyLimiter::new(1);
466        let _permit = limiter.try_acquire().unwrap();
467
468        let result = limiter.try_acquire();
469        assert!(result.is_err_and(|error| error.kind() == ErrorKind::AtCapacity));
470    }
471
472    #[test]
473    fn permit_recovery_after_drop() {
474        let limiter = ConcurrencyLimiter::new(1);
475
476        let permit = limiter.try_acquire().unwrap();
477        assert!(limiter.try_acquire().is_err());
478
479        drop(permit);
480        assert!(limiter.try_acquire().is_ok());
481    }
482
483    #[tokio::test(start_paused = true)]
484    async fn emitter_calls_callback() {
485        let limiter = ConcurrencyLimiter::new(5);
486        let _permit = limiter.try_acquire().unwrap();
487
488        let emitted_in_use = Arc::new(AtomicU32::new(0));
489        let emitted_queued = Arc::new(AtomicU32::new(0));
490        let in_use_clone = Arc::clone(&emitted_in_use);
491        let queued_clone = Arc::clone(&emitted_queued);
492
493        let emitter = limiter.run_emitter(move |stats| {
494            let in_use_ref = Arc::clone(&in_use_clone);
495            let queued_ref = Arc::clone(&queued_clone);
496            async move {
497                in_use_ref.store(stats.in_use, Ordering::Relaxed);
498                queued_ref.store(stats.queued, Ordering::Relaxed);
499            }
500        });
501
502        tokio::select! {
503            never = emitter => never,
504            _ = tokio::time::sleep(EMITTER_INTERVAL) => {}
505        }
506
507        assert_eq!(emitted_in_use.load(Ordering::Relaxed), 1);
508        assert_eq!(emitted_queued.load(Ordering::Relaxed), 0);
509    }
510
511    #[tokio::test]
512    async fn wait_all_resolves_when_permits_returned() {
513        let limiter = ConcurrencyLimiter::new(2);
514        let p1 = limiter.try_acquire().unwrap();
515        let p2 = limiter.try_acquire().unwrap();
516
517        let mut wait = Box::pin(limiter.wait_all());
518
519        // Dropping one permit is not enough.
520        drop(p1);
521        assert!(futures::poll!(&mut wait).is_pending());
522
523        // Dropping the last permit should resolve it.
524        drop(p2);
525        assert!(futures::poll!(&mut wait).is_ready());
526    }
527
528    #[tokio::test]
529    async fn wait_all_returns_immediately_when_empty() {
530        let limiter = ConcurrencyLimiter::new(5);
531        let wait = Box::pin(limiter.wait_all());
532        assert!(futures::poll!(wait).is_ready());
533    }
534
535    // --- Queue tests ---
536
537    #[tokio::test(start_paused = true)]
538    async fn queue_zero_rejects_immediately() {
539        let limiter = ConcurrencyLimiter::new(2);
540        assert_eq!(limiter.total_queue(), 0);
541
542        let p1 = limiter.try_acquire().unwrap();
543        let p2 = limiter.try_acquire().unwrap();
544        assert!(
545            limiter
546                .try_acquire()
547                .is_err_and(|error| error.kind() == ErrorKind::AtCapacity)
548        );
549
550        drop(p1);
551        assert!(limiter.try_acquire().is_ok());
552        drop(p2);
553
554        // Bulk holding all permits also rejects instantly (no timeout wait).
555        let mut bulk_permits = Vec::new();
556        for _ in 0..2 {
557            let permit = limiter.acquire_bulk().await.unwrap();
558            bulk_permits.push(permit);
559        }
560
561        let start = tokio::time::Instant::now();
562        let result = limiter.acquire().await;
563        assert!(result.is_err_and(|error| error.kind() == ErrorKind::AtCapacity));
564        assert_eq!(start.elapsed(), Duration::ZERO);
565        drop(bulk_permits);
566    }
567
568    #[tokio::test(start_paused = true)]
569    async fn acquire_succeeds_immediately_when_available() {
570        let limiter = ConcurrencyLimiter::new(2).with_queue(3);
571
572        let permit = limiter.acquire().await.unwrap();
573        assert_eq!(limiter.used_permits(), 1);
574        assert_eq!(limiter.queued_permits(), 0);
575        drop(permit);
576    }
577
578    #[tokio::test(start_paused = true)]
579    async fn acquire_waits_and_succeeds_after_release() {
580        let limiter = ConcurrencyLimiter::new(1).with_queue(2);
581
582        let held = limiter.acquire().await.unwrap();
583        assert_eq!(limiter.used_permits(), 1);
584
585        let limiter2 = limiter.clone();
586        let waiter = tokio::spawn(async move { limiter2.acquire().await });
587
588        tokio::task::yield_now().await;
589        assert_eq!(limiter.queued_permits(), 1);
590
591        drop(held);
592
593        let permit = waiter.await.unwrap().unwrap();
594        assert_eq!(limiter.used_permits(), 1);
595        assert_eq!(limiter.queued_permits(), 0);
596        drop(permit);
597    }
598
599    #[tokio::test(start_paused = true)]
600    async fn acquire_times_out() {
601        let limiter = ConcurrencyLimiter::new(1).with_queue(2);
602
603        let _held = limiter.acquire().await.unwrap();
604
605        let limiter2 = limiter.clone();
606        let waiter = tokio::spawn(async move { limiter2.acquire().await });
607
608        tokio::time::sleep(Duration::from_secs(2)).await;
609
610        let result = waiter.await.unwrap();
611        assert!(result.is_err_and(|error| error.kind() == ErrorKind::AtCapacity));
612        assert_eq!(limiter.queued_permits(), 0);
613    }
614
615    #[tokio::test(start_paused = true)]
616    async fn acquire_rejects_over_max_plus_queue() {
617        let limiter = ConcurrencyLimiter::new(1).with_queue(1);
618
619        let _held = limiter.acquire().await.unwrap();
620
621        let limiter2 = limiter.clone();
622        let _waiter = tokio::spawn(async move { limiter2.acquire().await });
623        tokio::task::yield_now().await;
624
625        assert_eq!(limiter.queued_permits(), 1);
626        let result = limiter.acquire().await;
627        assert!(result.is_err_and(|error| error.kind() == ErrorKind::AtCapacity));
628    }
629
630    #[tokio::test(start_paused = true)]
631    async fn dropping_parked_acquire_releases_queue_slot() {
632        let limiter = ConcurrencyLimiter::new(1).with_queue(1);
633
634        let _held = limiter.acquire().await.unwrap();
635
636        let limiter2 = limiter.clone();
637        let waiter = tokio::spawn(async move { limiter2.acquire().await });
638        tokio::task::yield_now().await;
639        assert_eq!(limiter.queued_permits(), 1);
640
641        waiter.abort();
642        let _ = waiter.await;
643        tokio::task::yield_now().await;
644
645        assert_eq!(limiter.queued_permits(), 0);
646
647        let limiter3 = limiter.clone();
648        let replacement = tokio::spawn(async move { limiter3.acquire().await });
649        tokio::task::yield_now().await;
650        assert_eq!(limiter.queued_permits(), 1);
651        drop(replacement);
652    }
653
654    #[tokio::test(start_paused = true)]
655    async fn queued_permits_reflects_state() {
656        let limiter = ConcurrencyLimiter::new(2).with_queue(3);
657
658        assert_eq!(limiter.queued_permits(), 0);
659        let _p1 = limiter.try_acquire().unwrap();
660        assert_eq!(limiter.queued_permits(), 0);
661        let _p2 = limiter.try_acquire().unwrap();
662        assert_eq!(limiter.queued_permits(), 0);
663        drop(_p1);
664        drop(_p2);
665
666        // Exact count when bulk holds permits.
667        let _bulk = limiter.acquire_bulk().await.unwrap();
668        let _bulk2 = limiter.acquire_bulk().await.unwrap();
669        assert_eq!(limiter.queued_permits(), 0);
670
671        let limiter2 = limiter.clone();
672        let _waiter = tokio::spawn(async move { limiter2.acquire().await });
673        tokio::task::yield_now().await;
674        assert_eq!(limiter.queued_permits(), 1);
675    }
676
677    #[tokio::test(start_paused = true)]
678    async fn acquire_rejects_immediately_when_max_is_zero() {
679        let limiter = ConcurrencyLimiter::new(0).with_queue(5);
680
681        let start = tokio::time::Instant::now();
682        let result = limiter.acquire().await;
683        assert!(result.is_err_and(|error| error.kind() == ErrorKind::AtCapacity));
684        assert_eq!(start.elapsed(), Duration::ZERO);
685    }
686
687    #[tokio::test(start_paused = true)]
688    async fn emitter_reports_queued_count() {
689        let limiter = ConcurrencyLimiter::new(1).with_queue(2);
690        let _held = limiter.acquire().await.unwrap();
691
692        let limiter2 = limiter.clone();
693        let _waiter = tokio::spawn(async move { limiter2.acquire().await });
694        tokio::task::yield_now().await;
695
696        let emitted_in_use = Arc::new(AtomicU32::new(0));
697        let emitted_queued = Arc::new(AtomicU32::new(0));
698        let in_use_clone = Arc::clone(&emitted_in_use);
699        let queued_clone = Arc::clone(&emitted_queued);
700
701        let emitter = limiter.run_emitter(move |stats| {
702            let in_use_ref = Arc::clone(&in_use_clone);
703            let queued_ref = Arc::clone(&queued_clone);
704            async move {
705                in_use_ref.store(stats.in_use, Ordering::Relaxed);
706                queued_ref.store(stats.queued, Ordering::Relaxed);
707            }
708        });
709
710        tokio::select! {
711            never = emitter => never,
712            _ = tokio::time::sleep(EMITTER_INTERVAL) => {}
713        }
714
715        assert_eq!(emitted_in_use.load(Ordering::Relaxed), 1);
716        assert_eq!(emitted_queued.load(Ordering::Relaxed), 1);
717    }
718
719    // --- Bulk tests ---
720
721    #[test]
722    fn bulk_defaults_to_full_capacity() {
723        let limiter = ConcurrencyLimiter::new(100);
724        assert_eq!(limiter.total_bulk(), 100);
725    }
726
727    #[test]
728    fn bulk_percent_computes_correctly() {
729        let limiter = ConcurrencyLimiter::new(100).with_bulk(60);
730        assert_eq!(limiter.total_bulk(), 60);
731
732        let limiter = ConcurrencyLimiter::new(10).with_bulk(90);
733        assert_eq!(limiter.total_bulk(), 9);
734
735        let limiter = ConcurrencyLimiter::new(100).with_bulk(150);
736        assert_eq!(limiter.total_bulk(), 100);
737
738        // Allow at least one bulk permit even when the percentage is zero.
739        let limiter = ConcurrencyLimiter::new(1).with_bulk(60);
740        assert_eq!(limiter.total_bulk(), 1);
741    }
742
743    #[tokio::test(start_paused = true)]
744    async fn bulk_caps_at_budget() {
745        let limiter = ConcurrencyLimiter::new(10).with_queue(5).with_bulk(90);
746        let bulk_budget = limiter.total_bulk();
747        assert_eq!(bulk_budget, 9);
748
749        let mut permits = Vec::new();
750        for _ in 0..bulk_budget {
751            let permit = limiter.acquire_bulk().await.unwrap();
752            permits.push(permit);
753        }
754
755        assert_eq!(limiter.used_bulk_permits(), bulk_budget);
756        assert_eq!(limiter.used_permits(), bulk_budget);
757
758        // Normal request can still acquire the remaining permit.
759        let normal = limiter.acquire().await.unwrap();
760        assert_eq!(limiter.used_permits(), 10);
761        drop(normal);
762        drop(permits);
763    }
764
765    #[tokio::test(start_paused = true)]
766    async fn normal_uses_all_permits_when_bulk_idle() {
767        let limiter = ConcurrencyLimiter::new(10).with_queue(5);
768
769        let mut permits = Vec::new();
770        for _ in 0..10 {
771            let permit = limiter.acquire().await.unwrap();
772            permits.push(permit);
773        }
774
775        assert_eq!(limiter.used_permits(), 10);
776        assert_eq!(limiter.used_bulk_permits(), 0);
777        drop(permits);
778    }
779
780    #[tokio::test(start_paused = true)]
781    async fn bulk_waits_for_inner_permit() {
782        let limiter = ConcurrencyLimiter::new(1).with_queue(2);
783
784        let held = limiter.acquire().await.unwrap();
785        assert_eq!(limiter.used_permits(), 1);
786
787        let limiter2 = limiter.clone();
788        let waiter = tokio::spawn(async move { limiter2.acquire_bulk().await });
789        tokio::task::yield_now().await;
790
791        drop(held);
792
793        let permit = waiter.await.unwrap().unwrap();
794        assert_eq!(limiter.used_permits(), 1);
795        assert_eq!(limiter.used_bulk_permits(), 1);
796        drop(permit);
797    }
798
799    #[tokio::test(start_paused = true)]
800    async fn bulk_timeout_spans_both_waits() {
801        let limiter = ConcurrencyLimiter::new(1);
802
803        let _held = limiter.acquire().await.unwrap();
804
805        let limiter2 = limiter.clone();
806        let waiter = tokio::spawn(async move { limiter2.acquire_bulk().await });
807
808        tokio::time::sleep(Duration::from_secs(2)).await;
809
810        let result = waiter.await.unwrap();
811        assert!(result.is_err_and(|error| error.kind() == ErrorKind::AtCapacity));
812        assert_eq!(limiter.used_bulk_permits(), 0);
813    }
814
815    #[tokio::test(start_paused = true)]
816    async fn bulk_cancellation_leaks_nothing() {
817        let limiter = ConcurrencyLimiter::new(2).with_queue(2);
818
819        let _held1 = limiter.acquire().await.unwrap();
820        let _held2 = limiter.acquire().await.unwrap();
821
822        let limiter2 = limiter.clone();
823        let waiter = tokio::spawn(async move { limiter2.acquire_bulk().await });
824        tokio::task::yield_now().await;
825
826        waiter.abort();
827        let _ = waiter.await;
828        tokio::task::yield_now().await;
829
830        assert_eq!(limiter.used_bulk_permits(), 0);
831        assert_eq!(limiter.used_permits(), 2);
832    }
833
834    #[tokio::test(start_paused = true)]
835    async fn bulk_rejects_immediately_when_max_is_zero() {
836        let limiter = ConcurrencyLimiter::new(0).with_queue(5);
837
838        let start = tokio::time::Instant::now();
839        let result = limiter.acquire_bulk().await;
840        assert!(result.is_err_and(|error| error.kind() == ErrorKind::AtCapacity));
841        assert_eq!(start.elapsed(), Duration::ZERO);
842    }
843
844    #[tokio::test(start_paused = true)]
845    async fn bulk_with_zero_percent_allows_one() {
846        let limiter = ConcurrencyLimiter::new(10).with_bulk(0);
847
848        assert_eq!(limiter.total_bulk(), 1);
849
850        let permit = limiter.acquire_bulk().await.unwrap();
851        assert_eq!(limiter.used_bulk_permits(), 1);
852
853        let limiter2 = limiter.clone();
854        let waiter = tokio::spawn(async move { limiter2.acquire_bulk().await });
855        tokio::time::sleep(Duration::from_secs(2)).await;
856
857        let result = waiter.await.unwrap();
858        assert!(result.is_err_and(|error| error.kind() == ErrorKind::AtCapacity));
859        drop(permit);
860    }
861
862    #[tokio::test(start_paused = true)]
863    async fn queue_bounded_under_bulk_load() {
864        let limiter = ConcurrencyLimiter::new(3).with_queue(2);
865
866        let mut bulk_permits = Vec::new();
867        for _ in 0..3 {
868            let permit = limiter.acquire_bulk().await.unwrap();
869            bulk_permits.push(permit);
870        }
871
872        let limiter2 = limiter.clone();
873        let _w1 = tokio::spawn(async move { limiter2.acquire().await });
874        tokio::task::yield_now().await;
875        assert_eq!(limiter.queued_permits(), 1);
876
877        let limiter3 = limiter.clone();
878        let _w2 = tokio::spawn(async move { limiter3.acquire().await });
879        tokio::task::yield_now().await;
880        assert_eq!(limiter.queued_permits(), 2);
881
882        // Third waiter exceeds queue depth — rejected instantly.
883        let start = tokio::time::Instant::now();
884        let result = limiter.acquire().await;
885        assert!(result.is_err_and(|error| error.kind() == ErrorKind::AtCapacity));
886        assert_eq!(start.elapsed(), Duration::ZERO);
887
888        drop(bulk_permits);
889    }
890}