Struct CircuitBreaker 

pub struct CircuitBreaker<L, C = SystemClock>
where
    C: Clock,
{ /* private fields */ }

Available on crate feature circuit-breaker only.

A circuit breaker wrapping a limiter L, timed by clock C.

Construct one with CircuitBreaker::builder. Build requires the circuit-breaker feature.

Examples

use std::time::Duration;
use throttle_net::{CircuitBreaker, Throttle, Trip};

let breaker = CircuitBreaker::builder()
    .trip(Trip::Consecutive(5))
    .cooldown(Duration::from_secs(10))
    .build(Throttle::per_second(100));

match breaker.acquire().await {
    Ok(permit) => {
        // ... call the downstream ...
        let ok = true;
        if ok { permit.success() } else { permit.failure() }
    }
    Err(_shed) => {
        // breaker open (or limiter exhausted): fail fast
    }
}

Implementations

impl CircuitBreaker<Infallible>

pub fn builder() -> CircuitBreakerBuilder

Starts building a breaker. Defaults: Trip::Consecutive(5), a 30-second cooldown, and a single trial that must succeed to close.

impl<L, C> CircuitBreaker<L, C>

where L: Limiter, C: Clock + Clone,

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

where C2: Clock + Clone,

Replaces the time source (the cooldown clock), for deterministic tests. The breaker is reset to closed around the new clock.

pub fn state(&self) -> BreakerState

The current state (a momentary snapshot).

pub fn inner(&self) -> &L

A shared reference to the wrapped limiter.

pub fn record_success(&self)

Reports a successful protected call. Prefer settling a Permit.

pub fn record_failure(&self)

Reports a failed protected call. Prefer settling a Permit.

pub fn try_acquire(&self) -> Result<Option<Permit<'_, L, C>>, ThrottleError>

Attempts to admit a request without waiting, returning a Permit on success.

Errors

• ThrottleError::CircuitOpen when the breaker is open (or its half-open trials are full): the request is shed without touching the wrapped limiter.
• ThrottleError::CostExceedsCapacity when the wrapped limiter can never grant a single unit.

Returns Ok(None) when the breaker would admit but the wrapped limiter has no token available right now (normal rate-limiting, not a breaker fault).

impl<L, C> CircuitBreaker<L, C>

where L: Limiter, C: Clock + Clone,

pub async fn acquire(&self) -> Result<Permit<'_, L, C>, ThrottleError>

Available on crate feature runtime only.

Admits a request, failing fast if the breaker is open and otherwise pacing on the wrapped limiter until a token is free.

A circuit-open condition returns immediately (load shedding); a plain rate-limit waits. Returns a Permit to settle with the call’s outcome.

Errors

• ThrottleError::CircuitOpen when the breaker is open or its trials are full — returned without waiting.
• ThrottleError::CostExceedsCapacity when the wrapped limiter can never grant the request.