Struct Queue 

pub struct Queue<L, K = (), C = SystemClock>
where
    K: Eq + Hash + Clone + Send + Sync,
    C: Clock,
{ /* private fields */ }

Available on crate feature runtime only.

A bounded, deadline-aware, priority queue fronting a limiter L, keyed by K for fairness and timed by clock C.

Build one with Queue::builder. Use K = () for a plain priority queue with no cross-key fairness.

Examples

use std::time::Duration;
use throttle_net::{Overflow, Queue, Throttle};

// 50 req/s, with room for 100 waiters; reject when full.
let queue: Queue<Throttle, &str> = Queue::builder()
    .capacity(100)
    .overflow(Overflow::DropOldest)
    .build(Throttle::per_second(50));

// Wait for a slot, but give up after 2 seconds.
queue
    .acquire("tenant:1", 0, Some(Duration::from_secs(2)))
    .await?;

Implementations

impl Queue<Infallible, ()>

pub fn builder() -> QueueBuilder

Starts building a queue.

impl<L, K, C> Queue<L, K, C>

where L: Limiter, K: Eq + Hash + Clone + Send + Sync, C: Clock + Clone,

pub fn with_clock<C2>(self, clock: C2) -> Queue<L, K, C2>

where C2: Clock + Clone,

Replaces the time source (the deadline clock), for deterministic tests. The queue is rebuilt empty around the new clock.

pub fn len(&self) -> usize

The number of waiters currently enqueued (a momentary snapshot).

pub fn is_empty(&self) -> bool

Returns true if no waiters are enqueued.

pub fn capacity(&self) -> usize

The configured waiter capacity.

pub fn inner(&self) -> &L

A shared reference to the wrapped limiter.

pub async fn acquire( &self, key: K, priority: u32, deadline: Option<Duration>, ) -> Result<(), ThrottleError>

Acquires one token, waiting in the queue until served, the deadline passes, or the overflow policy turns the request away.

priority orders waiters (higher first). key is the fairness key — equal-priority waiters are served round-robin across keys. deadline is a wait budget; None waits indefinitely.

Errors

• ThrottleError::QueueFull when the queue is full and the policy rejects (or evicts) this request.
• ThrottleError::DeadlineExceeded when the deadline passes first.
• ThrottleError::CostExceedsCapacity when the wrapped limiter can never grant a single unit.