Struct ConcurrencyLimiter 

pub struct ConcurrencyLimiter { /* private fields */ }

Limits concurrent backend operations and tracks in-flight count.

Permits are acquired with acquire or acquire_bulk and automatically returned when the ConcurrencyPermit is dropped.

Bulk operations use a separate budget semaphore that limits how many execution slots they may occupy. This is intended as a safe operating point — below this level there should be little-to-no performance degradation, leaving room for more tasks to be admitted via the queue before rejection is necessary.

Implementations

impl ConcurrencyLimiter

pub fn new(max: u32) -> Self

Creates a new limiter with the given maximum number of permits.

By default the queue depth is zero, preserving the original try-or-reject behavior. Use with_queue to enable bounded waiting.

The bulk budget defaults to 100% of max (no restriction); use with_bulk to set a safe operating point for bulk traffic.

pub fn with_queue(self, size: u32) -> Self

Enables bounded waiting when all execution permits are held.

Up to size additional callers may park in acquire waiting for a permit. Callers beyond that are rejected immediately.

pub fn with_timeout(self, timeout: Duration) -> Self

Sets the maximum time a caller may wait for a permit.

Applies to both acquire (when parked in the queue) and acquire_bulk (waiting for the bulk and execution semaphores). Defaults to 1 second.

pub fn with_bulk(self, percent: u32) -> Self

Sets the bulk concurrency budget as a percentage of max.

percent is clamped to 1..=100. At 100 (the default), bulk operations can use all execution slots. Lower values set a safe operating point below which there is little-to-no performance degradation, allowing more tasks to queue before rejection is necessary — e.g. 60 means bulk operations can hold at most 60% of permits.

pub async fn acquire(&self) -> Result<ConcurrencyPermit>

Acquires a single concurrency permit, waiting if necessary.

If a permit is free, returns immediately without touching the queue. Otherwise, acquires a queue ticket (bounded by the queue depth) and waits up to the configured timeout. Returns Error::AtCapacity if the queue is full or on timeout.

pub fn try_acquire(&self) -> Result<ConcurrencyPermit>

Tries to acquire a single permit without waiting.

Returns Error::AtCapacity when no permits are available.

pub async fn acquire_bulk(&self) -> Result<ConcurrencyPermit>

Acquires a single permit for a bulk operation, waiting if necessary.

Bulk operations are bounded by the bulk budget — a safe operating point below which there is little-to-no performance degradation. Both the bulk semaphore and the inner execution semaphore are acquired under a single timeout deadline configured via with_timeout.

Returns Error::AtCapacity on timeout or when max is zero.

pub fn available_permits(&self) -> u32

Returns the number of permits currently available.

pub fn used_permits(&self) -> u32

Returns the number of permits currently held.

pub fn total_permits(&self) -> u32

Returns the total number of permits.

pub fn queued_permits(&self) -> u32

Returns the number of callers currently waiting in the queue.

pub fn total_queue(&self) -> u32

Returns the configured queue capacity.

pub fn used_bulk_permits(&self) -> u32

Returns the number of bulk permits currently held.

pub fn total_bulk(&self) -> u32

Returns the bulk concurrency budget.

pub async fn wait_all(&self)

Waits until all permits have been returned.

pub fn stats(&self) -> Stats

Returns a snapshot of the current counts.

pub async fn run_emitter<F, Fut>(&self, emit: F)

where F: FnMut(Stats) -> Fut, Fut: Future<Output = ()>,

Periodically calls emit with the current in-use and queued counts.

This future runs forever and is intended to be spawned as a background task alongside the service.

Trait Implementations

impl Clone for ConcurrencyLimiter

fn clone(&self) -> ConcurrencyLimiter

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ConcurrencyLimiter

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.