Struct BackpressureGuard 

pub struct BackpressureGuard { /* private fields */ }

Tracks in-flight work count and enforces a capacity limit.

Guarantees

• Thread-safe via Arc<Mutex<_>>
• try_acquire is non-blocking
• release decrements the counter; no-op if counter is already 0
• Optional soft limit emits a warning when depth reaches the threshold

Implementations

impl BackpressureGuard

pub fn new(capacity: usize) -> Result<Self, AgentRuntimeError>

Create a new guard with the given capacity.

Returns

• Ok(BackpressureGuard) — on success
• Err(AgentRuntimeError::Orchestration) — if capacity == 0

pub fn with_soft_limit(self, soft: usize) -> Result<Self, AgentRuntimeError>

Set a soft capacity threshold. When depth reaches this level, a warning is logged but the request is still accepted (up to hard capacity).

pub fn try_acquire(&self) -> Result<(), AgentRuntimeError>

Try to acquire a slot.

Emits a warning when the soft limit is reached (if configured), but still accepts the request until hard capacity is exceeded.

Returns

• Ok(()) — slot acquired
• Err(AgentRuntimeError::BackpressureShed) — hard capacity exceeded

pub fn release(&self) -> Result<(), AgentRuntimeError>

Release a previously acquired slot.

pub fn reset(&self)

Reset the current depth to zero.

Useful in tests or after a controlled shutdown when all in-flight requests have been cancelled and the guard should start fresh.

pub fn is_full(&self) -> Result<bool, AgentRuntimeError>

Return true if the guard is at or over its hard capacity.

pub fn is_empty(&self) -> Result<bool, AgentRuntimeError>

Return true if no slots are currently in use.

pub fn available_capacity(&self) -> Result<usize, AgentRuntimeError>

Return the number of additional request slots available before the hard cap.

pub fn hard_capacity(&self) -> usize

Return the hard capacity (maximum concurrent slots) configured for this guard.

pub fn soft_limit(&self) -> Option<usize>

Return the soft capacity limit if one was configured, or None.

pub fn is_soft_limited(&self) -> bool

Return true if a soft capacity limit has been configured.

Equivalent to self.soft_limit().is_some() but more readable at call sites that only need a boolean check.

pub fn depth(&self) -> Result<usize, AgentRuntimeError>

Return the current depth.

pub fn percent_full(&self) -> Result<f64, AgentRuntimeError>

Return the current depth as a percentage of the hard capacity.

Returns a value in [0.0, 100.0]. When depth > capacity (which cannot happen in normal operation) the result is clamped to 100.0.

pub fn soft_depth_ratio(&self) -> f32

Return the ratio of current depth to soft capacity as a value in [0.0, ∞).

Returns 0.0 if no soft limit has been configured. Values above 1.0 mean the soft limit has been exceeded.

pub fn utilization_ratio(&self) -> Result<f32, AgentRuntimeError>

Return the fraction of the hard capacity currently in use: depth / capacity.

Returns 0.0 when no slots are in use, 1.0 when fully saturated.

pub fn remaining_capacity(&self) -> Result<usize, AgentRuntimeError>

Return the number of additional slots that can be acquired before hitting the hard capacity limit.

Returns 0 when the guard is full.

pub fn reset_depth(&self) -> Result<(), AgentRuntimeError>

Force the in-flight depth counter to zero.

Useful for test teardown or hard resets where acquired slots will never be released normally (e.g., after a test panics before calling release).

pub fn headroom_ratio(&self) -> Result<f64, AgentRuntimeError>

Return the fraction of capacity that is still available, in [0.0, 1.0].

1.0 means completely empty; 0.0 means at full capacity.

pub fn acquired_count(&self) -> Result<usize, AgentRuntimeError>

Return the number of currently held (acquired) slots.

Equivalent to capacity - available_capacity().

pub fn over_soft_limit(&self) -> Result<bool, AgentRuntimeError>

Return true if the current depth exceeds the configured soft limit.

Returns false if no soft limit is set.

Trait Implementations

impl Clone for BackpressureGuard

fn clone(&self) -> BackpressureGuard

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for BackpressureGuard

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

Formats the value using the given formatter.