Struct Bulkhead 

pub struct Bulkhead { /* private fields */ }

A concurrency limiter: a counting semaphore that caps in-flight operations.

Bulkhead is a small, Copy value holding a fixed capacity and the number of permits currently held (in_flight). try_acquire takes permits when room exists and reports whether it succeeded; release returns them.

The capacity is clamped to at least 1 at construction, so a bulkhead can always admit one operation. The invariant in_flight <= capacity holds on every public path, so available never underflows.

Implementations

impl Bulkhead

pub const fn new(capacity: usize) -> Self

Creates a bulkhead allowing at most capacity concurrent permits.

capacity is clamped to a minimum of 1: a bulkhead always admits at least one operation, so a 0 would only ever reject and is treated as 1.

Examples found in repository

examples/basic.rs (line 15)

fn main() {
    // Allow at most three concurrent calls to a downstream service.
    let mut bulkhead = Bulkhead::new(3);

    // Six requests arrive while none have finished yet.
    println!("capacity: {}", bulkhead.capacity());
    for request in 0..6 {
        if bulkhead.try_acquire_one() {
            println!(
                "request {request}: admitted ({} in flight)",
                bulkhead.in_flight()
            );
        // ... start the work; release the permit when it completes ...
        } else {
            println!("request {request}: rejected (bulkhead full), shed load");
        }
    }

    // Two of the in-flight operations finish and return their permits.
    bulkhead.release(2);
    println!(
        "\nafter two completions: {} available",
        bulkhead.available()
    );

    // Room exists again, so the next request is admitted.
    if bulkhead.try_acquire_one() {
        println!("retry: admitted ({} in flight)", bulkhead.in_flight());
    }
}

pub const fn capacity(&self) -> usize

Returns the maximum number of concurrent permits.

Examples found in repository

examples/basic.rs (line 18)

fn main() {
    // Allow at most three concurrent calls to a downstream service.
    let mut bulkhead = Bulkhead::new(3);

    // Six requests arrive while none have finished yet.
    println!("capacity: {}", bulkhead.capacity());
    for request in 0..6 {
        if bulkhead.try_acquire_one() {
            println!(
                "request {request}: admitted ({} in flight)",
                bulkhead.in_flight()
            );
        // ... start the work; release the permit when it completes ...
        } else {
            println!("request {request}: rejected (bulkhead full), shed load");
        }
    }

    // Two of the in-flight operations finish and return their permits.
    bulkhead.release(2);
    println!(
        "\nafter two completions: {} available",
        bulkhead.available()
    );

    // Room exists again, so the next request is admitted.
    if bulkhead.try_acquire_one() {
        println!("retry: admitted ({} in flight)", bulkhead.in_flight());
    }
}

pub const fn in_flight(&self) -> usize

Returns the number of permits currently held.

Examples found in repository

examples/basic.rs (line 23)

fn main() {
    // Allow at most three concurrent calls to a downstream service.
    let mut bulkhead = Bulkhead::new(3);

    // Six requests arrive while none have finished yet.
    println!("capacity: {}", bulkhead.capacity());
    for request in 0..6 {
        if bulkhead.try_acquire_one() {
            println!(
                "request {request}: admitted ({} in flight)",
                bulkhead.in_flight()
            );
        // ... start the work; release the permit when it completes ...
        } else {
            println!("request {request}: rejected (bulkhead full), shed load");
        }
    }

    // Two of the in-flight operations finish and return their permits.
    bulkhead.release(2);
    println!(
        "\nafter two completions: {} available",
        bulkhead.available()
    );

    // Room exists again, so the next request is admitted.
    if bulkhead.try_acquire_one() {
        println!("retry: admitted ({} in flight)", bulkhead.in_flight());
    }
}

pub const fn available(&self) -> usize

Returns how many more permits can be acquired right now.

Examples found in repository

examples/basic.rs (line 35)

fn main() {
    // Allow at most three concurrent calls to a downstream service.
    let mut bulkhead = Bulkhead::new(3);

    // Six requests arrive while none have finished yet.
    println!("capacity: {}", bulkhead.capacity());
    for request in 0..6 {
        if bulkhead.try_acquire_one() {
            println!(
                "request {request}: admitted ({} in flight)",
                bulkhead.in_flight()
            );
        // ... start the work; release the permit when it completes ...
        } else {
            println!("request {request}: rejected (bulkhead full), shed load");
        }
    }

    // Two of the in-flight operations finish and return their permits.
    bulkhead.release(2);
    println!(
        "\nafter two completions: {} available",
        bulkhead.available()
    );

    // Room exists again, so the next request is admitted.
    if bulkhead.try_acquire_one() {
        println!("retry: admitted ({} in flight)", bulkhead.in_flight());
    }
}

pub const fn is_full(&self) -> bool

Returns true when no further permits are available.

pub const fn is_empty(&self) -> bool

Returns true when no permits are held.

pub fn try_acquire(&mut self, permits: usize) -> bool

Tries to acquire permits permits at once.

Returns true and reserves them if at least permits are available; otherwise returns false and changes nothing (no partial acquire). A request for more than capacity always fails. Acquiring 0 permits always succeeds and reserves nothing.

pub fn try_acquire_one(&mut self) -> bool

Tries to acquire a single permit. See try_acquire.

Examples found in repository

examples/basic.rs (line 20)

fn main() {
    // Allow at most three concurrent calls to a downstream service.
    let mut bulkhead = Bulkhead::new(3);

    // Six requests arrive while none have finished yet.
    println!("capacity: {}", bulkhead.capacity());
    for request in 0..6 {
        if bulkhead.try_acquire_one() {
            println!(
                "request {request}: admitted ({} in flight)",
                bulkhead.in_flight()
            );
        // ... start the work; release the permit when it completes ...
        } else {
            println!("request {request}: rejected (bulkhead full), shed load");
        }
    }

    // Two of the in-flight operations finish and return their permits.
    bulkhead.release(2);
    println!(
        "\nafter two completions: {} available",
        bulkhead.available()
    );

    // Room exists again, so the next request is admitted.
    if bulkhead.try_acquire_one() {
        println!("retry: admitted ({} in flight)", bulkhead.in_flight());
    }
}

pub fn release(&mut self, permits: usize)

Releases permits permits back to the bulkhead.

Saturates at zero, so releasing more than are held simply empties the bulkhead rather than underflowing — a release without a matching acquire cannot drive in_flight negative or panic.

Examples found in repository

examples/basic.rs (line 32)

fn main() {
    // Allow at most three concurrent calls to a downstream service.
    let mut bulkhead = Bulkhead::new(3);

    // Six requests arrive while none have finished yet.
    println!("capacity: {}", bulkhead.capacity());
    for request in 0..6 {
        if bulkhead.try_acquire_one() {
            println!(
                "request {request}: admitted ({} in flight)",
                bulkhead.in_flight()
            );
        // ... start the work; release the permit when it completes ...
        } else {
            println!("request {request}: rejected (bulkhead full), shed load");
        }
    }

    // Two of the in-flight operations finish and return their permits.
    bulkhead.release(2);
    println!(
        "\nafter two completions: {} available",
        bulkhead.available()
    );

    // Room exists again, so the next request is admitted.
    if bulkhead.try_acquire_one() {
        println!("retry: admitted ({} in flight)", bulkhead.in_flight());
    }
}

pub fn release_one(&mut self)

Releases a single permit. See release.

pub fn reset(&mut self)

Releases every held permit, returning the bulkhead to empty.

Trait Implementations

impl Clone for Bulkhead

fn clone(&self) -> Bulkhead

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Copy for Bulkhead

impl Debug for Bulkhead

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

Formats the value using the given formatter.

impl Eq for Bulkhead

impl Hash for Bulkhead

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for Bulkhead

fn eq(&self, other: &Bulkhead) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl StructuralPartialEq for Bulkhead